مستندات

خطاها

شکل پاسخ خطا و معنی دقیق هر کد — با کاری که باید در برابرش بکنید.

شکل پاسخ خطا

همان شکلی که OpenAI برمی‌گرداند، پس مدیریت خطای موجود شما کار می‌کند. فیلد code دقیق‌ترین چیز است — بر اساس آن تصمیم بگیرید، نه بر اساس متن پیام.

json

{
  "error": {
    "message": "insufficient balance",
    "type": "insufficient_quota",
    "code": "insufficient_balance"
  }
}

code	معنی و کاری که باید کرد
`invalid_request`	بدنهٔ درخواست ایراد دارد — پیام دقیقاً می‌گوید کدام فیلد.
`request_exceeds_token_limit`	پرامپت + max_tokens از کل سقف توکن‌در‌دقیقهٔ شما بزرگ‌تر است. این هرگز با تلاش دوباره درست نمی‌شود: پرامپت را کوتاه کنید یا max_tokens را پایین بیاورید.
`streaming_disabled`	stream موقتاً غیرفعال است. با stream=false دوباره بفرستید.

code	معنی
`invalid_api_key`	کلید اشتباه، باطل‌شده یا منقضی است. شایع‌ترین علت واقعی: فاصله یا خط جدید اضافی هنگام کپی.

code	معنی و کاری که باید کرد
`insufficient_balance`	موجودی برای پوشش رزرو این درخواست کافی نیست. کیف پول را شارژ کنید — یا max_tokens را پایین بیاورید تا رزرو کوچک‌تر شود.
`monthly_cap_reached`	سقف خرج ماهانهٔ این کلید پر شده.
`plan_quota_reached`	سهمیهٔ توکن پلن تمام شده و پلن اجازهٔ مصرف مازاد نمی‌دهد.
`overage_disabled`	سهمیه تمام شده و مصرف مازاد برای این حساب روشن نیست. یا آن را روشن کنید یا کلید را اعتباری کنید.
`overage_limit_reached`	سقف مصرف مازاد پر شده.

code	معنی و کاری که باید کرد
`model_not_allowed`	این کلید عمداً به فهرست مشخصی از مدل‌ها محدود شده.
`model_not_in_plan`	مدل در پلن شما نیست. کلید را «اعتباری» کنید تا از کیف پول به همهٔ مدل‌ها دسترسی داشته باشید — توضیح.
`byok_disabled`	استفاده از کلید شخصی در کل پلتفرم خاموش است.

code	HTTP	معنی
`model_not_found`	404	شناسهٔ مدل ناشناخته است — یا وجود ندارد یا منتشر نشده.
`rate_limit_rpm / rph / rpd / tpm`	429	سقف نرخ همان پنجره پر شده. به retry-after احترام بگذارید.
`key_daily_token_budget_reached`	429	سقف روزانهٔ توکن کلید. نیمه‌شب تهران بازنشانی می‌شود.
`key_daily_budget_reached`	429	سقف روزانهٔ ریالی کلید.
`free_daily_limit`	429	سقف روزانهٔ پلن رایگان.
`global_throttle`	429	محدودیت موقت کل پلتفرم در زمان اوج.
`no_capacity`	503	فعلاً مسیر سالمی برای این مدل نیست. کمی بعد دوباره تلاش کنید.
`gateway_paused`	503	سرویس در حالت تعمیرات است.
`pricing_unavailable`	503	نرخ فعالی برای قیمت‌گذاری نیست؛ ما ترجیح می‌دهیم کور شارژ نکنیم.

کدام‌ها ارزش تلاش دوباره دارند و کدام‌ها نه:

قابل تلاش دوباره: 429 (پس از retry-after), 503 no_capacity, 5xx بالادست — با عقب‌نشینی نمایی.
بی‌فایده: 400, 401, 403, 404 — تا وقتی خودِ درخواست عوض نشود، جواب عوض نمی‌شود.
نیازمند اقدام انسان: 402 — شارژ یا تغییر تنظیمات لازم است.

مقدار هدر x-request-id را بفرستید. با آن دقیقاً همان درخواست را پیدا می‌کنیم — بدون آن باید حدس بزنیم.