خطاها و روش بازیابی
ساختار خطا، کدهای 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
}
}
}مرجع خطا
کدها، علت و راهحل
400
streaming_not_supportedstream برابر true است.
stream را false کنید یا حذف کنید.401
missing_api_keyهدر Authorization ارسال نشده است.
Bearer token را به هدر اضافه کنید.401
invalid_api_keyفرمت کلید اشتباه است، کلید لغو شده یا وجود ندارد.
کلید را دوباره از پنل بررسی یا جایگزین کنید.402
upgrade_requiredپلن API و موجودی pay-as-you-go ندارید.
پلن مناسب یا اعتبار API تهیه کنید.402
api_credits_exhaustedسهمیه و موجودی برای هزینهٔ مدل کافی نیست.
مصرف را بررسی و موجودی را شارژ کنید.403
account_unavailableحساب تأییدنشده، غیرفعال یا مسدود است.
وضعیت حساب را بررسی کنید.404
model_not_foundمدل وجود ندارد یا برای پلن مجاز نیست.
مدل را از GET /models انتخاب کنید.413
input_too_largeمجموع ورودی از ۲۴٬۰۰۰ کاراکتر بیشتر است.
تاریخچه یا متن ورودی را کوتاه کنید.422
messages_requiredهیچ پیام یا prompt معتبری وجود ندارد.
messages یا یکی از prompt/message/input را ارسال کنید.429
rate_limit_exceededسقف درخواست حساب یا کلید پر شده است.
طبق Retry-After با backoff تلاش کنید.502
upstream_errorسرویس مدل پاسخ معتبر نداده است.
با retry محدود تکرار کنید؛ اعتبار رزروشده برگردانده میشود.503
system_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}`)
}