خطاها

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

شکل پاسخ خطا

همان شکلی که 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 دوباره بفرستید.
`invalid_provider_prefs`	فیلد provider نامعتبر است یا provider ناشناخته نام برده.
`upstream_bad_request`	بالادست بدنه را رد کرد؛ پیام همان توضیح بالادست است.

۴۰۱ — احراز هویت

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

۴۰۲ — موجودی یا سهمیه

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

۴۰۳ — دسترسی

code	معنی و کاری که باید کرد
`guardrail_blocked`	یک گاردریل محتوای سازمان این درخواست را رد کرد (تزریق پرامپت یا اطلاعات حساس). پیام فقط دسته را می‌گوید، نه متن را.
`model_not_allowed_by_guardrail`	یکی از گاردریل‌های سازمان این مدل را مجاز نمی‌داند (هدر X-IranRouter-Guardrail).
`model_not_allowed`	این کلید عمداً به فهرست مشخصی از مدل‌ها محدود شده.
`model_not_in_plan`	مدل در پلن شما نیست. کلید را «اعتباری» کنید تا از کیف پول به همهٔ مدل‌ها دسترسی داشته باشید — توضیح.
`byok_disabled`	استفاده از کلید شخصی در کل پلتفرم خاموش است.
`model_not_in_free_tier`	پلن رایگان فقط مدل‌های رایگان را می‌بیند.

۴۰۴ / ۴۲۹ / ۵۰۳

code	HTTP	معنی
`invalid_preset`	400	نام پریست فقط حروف کوچک انگلیسی، عدد و خط‌تیره است.
`storage_unavailable`	507 / 503	فضای ذخیرهٔ فایل در دسترس نیست: ۵۰۷ هنگام آپلود (گاهی موقت، گاهی چون این سرویس فعلاً فایل نگه نمی‌دارد — متن خطا می‌گوید کدام)، ۵۰۳ هنگام خواندن.
`preset_not_found`	404	پریستی با این شناسه در فضای کارِ این کلید نیست. پریست‌ها به فضای کار تعلق دارند (@preset/شناسه).
`context_length_exceeded`	400	متن گفتگو حتی با خوش‌بینانه‌ترین شمارش در پنجرهٔ context مدل جا نمی‌شود. خودِ این رد هزینه‌ای ندارد (ولی OCRِ پلاگین file-parser که پیش از آن اجرا شده، درخواست جداگانه‌ای بوده و حساب شده). کوتاهش کنید یا transforms: ["middle-out"] بفرستید.
`file_parser_failed / file_parser_unavailable / too_many_files`	4xx / 502	پلاگین file-parser: سند خوانده نشد یا متنی از آن درنیامد (با همان وضعیتی که خودِ OCR داد)، پلاگین روی این سرویس پیکربندی نشده، یا بیش از ۴ PDF در یک درخواست.
`file_parser_daily_pages`	429	پلن رایگان سقف روزانهٔ صفحات file-parser را پر کرده؛ Retry-After تا نیمه‌شب تهران.
`invalid_plugins`	400	نام پلاگین یا transform ناشناخته است. مجازها: web، response-healing، file-parser و middle-out.
`model_not_found`	404	شناسهٔ مدل ناشناخته است — یا وجود ندارد یا منتشر نشده. برای iranrouter/auto: tier ناشناخته یا tierای که فعلاً مدلی ندارد.
`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	نرخ فعالی برای قیمت‌گذاری نیست؛ ما ترجیح می‌دهیم کور شارژ نکنیم.
`byok_rate_limited`	429	سقف نرخ providerِ کلید شخصی شما.
`server_overloaded / load_shed`	503	ظرفیت هم‌زمانی پر است، یا در اوج بار ترافیک این پلن موقتاً کنار گذاشته می‌شود. به retry-after احترام بگذارید.
`model_in_maintenance`	503	مدل موقتاً از سرویس خارج است.

۴۰۹ / ۴۱۰ / ۴۱۳ / ۵۰۲

code	HTTP	معنی
`idempotency_in_flight`	409	درخواست اصلی با همین Idempotency-Key هنوز در حال اجراست.
`idempotency_completed_unreplayable`	409	درخواست اصلی کامل شد ولی پاسخش برای بازپخش خیلی بزرگ بود.
`model_sunset`	410	مدل منسوخ شده و تاریخ خاموشی‌اش گذشته؛ به جانشین (هدر X-IranRouter-Successor) مهاجرت کنید.
`payload_too_large`	413	بدنه یا فایل از سقف حجم بزرگ‌تر است.
`upstream_error:*`	502	بالادست پس از همهٔ تلاش‌ها شکست خورد؛ پسوند نوع خطا را می‌گوید. چیزی شارژ نشده.

الگوی تلاش دوباره

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

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

وقتی به پشتیبانی پیام می‌دهید

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