مرجع

خطاها و پیام‌ها

همهٔ خطاها با یک ساختار JSON یکسان برمی‌گردند. کدهای خطا، وضعیت HTTP هر کدام و روش درست مدیریت ۴۲۹ و خطاهای اعتبار را اینجا ببینید.

نسخهٔ .md

ساختار پاسخ خطا

json

{
  "error": {
    "code": "invalid_request",
    "message": "..."
  }
}

کدهای خطا

HTTP	code	معنی	تکرار؟
401	`missing_authorization`	هدر Authorization ارسال نشده یا طرح Bearer ندارد	خیر
401	`invalid_api_key`	کلید نامعتبر است	خیر
403	`revoked_api_key`	کلید لغو شده است	خیر
403	`expired_api_key`	تاریخ انقضای کلید گذشته است	خیر
403	`ip_not_allowed`	IP درخواست در فهرست IPهای مجاز این کلید نیست	خیر
403	`model_not_allowed`	این کلید اجازهٔ استفاده از این مدل را ندارد	خیر
403	`spend_cap_exceeded`	سقف مصرف روزانه یا ماهانهٔ کلید پر شده (اول روز/ماه بعد، به وقت تهران، صفر می‌شود)	پس از شروع دورهٔ بعد
403	`user_banned`	حساب مسدود شده است	خیر
403	`insufficient_credits`	اعتبار کافی نیست (پیام مقدار لازم و موجودی را می‌گوید)	خیر
429	`rate_limit_exceeded`	بیش از سقف دقیقه‌ای (60 درخواست)	پس از Retry-After
400	`invalid_request`	بدنه یا پارامتر نامعتبر؛ پیام فیلد مشکل‌دار را می‌گوید	خیر
400	`unsupported_model`	شناسهٔ مدل برای این مسیر پشتیبانی نمی‌شود	خیر
400	`invalid_idempotency_key`	مقدار `Idempotency-Key` نامعتبر	خیر
404	`task_not_found`	تسکی با این شناسه برای این حساب وجود ندارد	خیر
409	`idempotency_key_in_progress`	درخواست قبلی با همین کلید هنوز در حال اجراست	پس از Retry-After
422	`idempotency_key_reused`	همان `Idempotency-Key` با بدنهٔ متفاوت	خیر
500	`generation_failed`	ارسال به مدل ناموفق بود؛ اعتباری رزرو نشده	بله
500	`internal_error`	خطای غیرمنتظرهٔ سرور	بله (با backoff)

خطای تسک با خطای HTTP فرق دارد: اگر تسک ثبت شود ولی تولید شکست بخورد، HTTP 200 است و status تسک failed و دلیل در error می‌آید؛ اعتباری کسر نمی‌شود.

محدودیت نرخ (429)

هدرهای مفید: Retry-After، X-RateLimit-Limit. برای 429 اعتباری کسر نمی‌شود.

صبر کنید تا Retry-After بگذرد، backoff کنید، و polling را هر ۳ تا ۵ ثانیه نگه دارید.