مستنداتخطاها
مدیریت API
مستندات API / خطاها

خطاها و روش بازیابی

ساختار خطا، کدهای HTTP و راه‌حل عملی برای هر خطای قابل بازگشت از API.

Error envelope

ساختار خطای دامنهٔ API

برای منطق برنامه از code استفاده کنید؛ message برای توضیح فنی و details برای اطلاعات تکمیلی است.
خطای دامنهJSON
{
  "error": {
    "code": "api_credits_exhausted",
    "message": "Your monthly API credits are exhausted...",
    "details": {
      "period": "2026-08",
      "used": 1000,
      "limit": 1000,
      "cost": 12,
      "api_credit_balance": 4
    }
  }
}

مرجع خطا

کدها، علت و راه‌حل

400streaming_not_supported

stream برابر true است.

stream را false کنید یا حذف کنید.
401missing_api_key

هدر Authorization ارسال نشده است.

Bearer token را به هدر اضافه کنید.
401invalid_api_key

فرمت کلید اشتباه است، کلید لغو شده یا وجود ندارد.

کلید را دوباره از پنل بررسی یا جایگزین کنید.
402upgrade_required

پلن API و موجودی pay-as-you-go ندارید.

پلن مناسب یا اعتبار API تهیه کنید.
402api_credits_exhausted

سهمیه و موجودی برای هزینهٔ مدل کافی نیست.

مصرف را بررسی و موجودی را شارژ کنید.
403account_unavailable

حساب تأییدنشده، غیرفعال یا مسدود است.

وضعیت حساب را بررسی کنید.
404model_not_found

مدل وجود ندارد یا برای پلن مجاز نیست.

مدل را از GET /models انتخاب کنید.
413input_too_large

مجموع ورودی از ۲۴٬۰۰۰ کاراکتر بیشتر است.

تاریخچه یا متن ورودی را کوتاه کنید.
422messages_required

هیچ پیام یا prompt معتبری وجود ندارد.

messages یا یکی از prompt/message/input را ارسال کنید.
429rate_limit_exceeded

سقف درخواست حساب یا کلید پر شده است.

طبق Retry-After با backoff تلاش کنید.
502upstream_error

سرویس مدل پاسخ معتبر نداده است.

با retry محدود تکرار کنید؛ اعتبار رزروشده برگردانده می‌شود.
503system_stopped

پذیرش درخواست موقتاً متوقف است.

بعداً دوباره تلاش کنید.

الگوی پیشنهادی

مدیریت خطای مقاوم

Error handlingJavaScript
const response = await fetch(url, options)
const payload = await response.json().catch(() => ({}))

if (!response.ok) {
  const error = payload.error
  const code = typeof error === 'object'
    ? error.code
    : 'invalid_http_request'
  const message = typeof error === 'object'
    ? error.message
    : error

  if (response.status === 429) {
    const wait = Number(response.headers.get('Retry-After') ?? 1)
    // retry with exponential backoff
  }

  throw new Error(`KujiChat API [${code}]: ${message}`)
}