خطاها

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

شکل پاسخ خطا

همان شکلی که 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_disabledstream موقتاً غیرفعال است. با stream=false دوباره بفرستید.
invalid_provider_prefsفیلد provider نامعتبر است یا provider ناشناخته نام برده.
upstream_bad_requestبالادست بدنه را رد کرد؛ پیام همان توضیح بالادست است.
wrong_endpointاین مدل روی این مسیر جواب نمی‌دهد: مدل‌هایی مثل مدل‌های تشخیص، طبقه‌بندی یا Judgment فقط از مسیر خودشان جواب می‌دهند. متن خطا مسیر درست را می‌گوید؛ درخواست را به همان بفرستید. چیزی شارژ نشده.
model_cannot_editاین مدل فقط از متن عکس می‌سازد و عکسی برای ویرایش نمی‌گیرد. برای /v1/images/edits مدلی را بگیرید که عکس هم می‌پذیرد. چیزی شارژ نشده.

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

codeمعنی
invalid_api_keyکلید اشتباه یا باطل‌شده است. شایع‌ترین علت واقعی: فاصله یا خط جدید اضافی هنگام کپی.
key_expiredکلید درست است ولی تاریخ انقضایش گذشته. در داشبورد کلید تازه بسازید.
invalid_management_keyروی مسیرهای /provision: کلید مدیریتی (irm-) نیست، اشتباه است یا باطل شده — کلید مدیریتی.

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

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).
ip_not_allowedاین کلید به چند IP یا بازه محدود شده و درخواست از نشانی دیگری آمده. فهرست را در داشبورد، ویرایش کلید، ببینید.
model_not_allowedاین کلید عمداً به فهرست مشخصی از مدل‌ها محدود شده.
model_not_in_planمدل در پلن شما نیست. کلید را «اعتباری» کنید تا از کیف پول به همهٔ مدل‌ها دسترسی داشته باشید — توضیح.
byok_disabledاستفاده از کلید اختصاصی (BYOK) موقتاً در کل سرویس خاموش است.
model_not_in_free_tierپلن رایگان فقط مدل‌های رایگان را می‌بیند.
file_add_forbiddenادمین این Workspace افزودن فایل را برای شما بسته است. از ادمین همان Workspace بخواهید.
file_download_forbiddenادمین این Workspace برداشتن فایل را برای شما بسته است: دانلود محتوای فایل، نتیجهٔ batch یا ویدئو. از ادمین همان Workspace بخواهید.
service_not_availableجست‌وجو یا خواندن صفحه (/v1/search، /v1/fetch) فعلاً از طرف ما بسته است. بعداً دوباره امتحان کنید.
management_key_readonlyکلید مدیریتی «فقط خواندن» است و فقط درخواست GET می‌فرستد.

۴۰۴ / ۴۲۹ / ۵۰۳

codeHTTPمعنی
invalid_preset400نام پریست فقط حروف کوچک انگلیسی، عدد و خط‌تیره است.
storage_unavailable507 / 503فضای ذخیرهٔ فایل در دسترس نیست: ۵۰۷ هنگام آپلود (گاهی موقت، گاهی چون این سرویس فعلاً فایل نگه نمی‌دارد — متن خطا می‌گوید کدام)، ۵۰۳ هنگام خواندن.
preset_not_found404پریستی با این شناسه در Workspace این کلید نیست. پریست‌ها به فضای کار تعلق دارند (@preset/شناسه).
context_length_exceeded400متن گفتگو حتی با خوش‌بینانه‌ترین شمارش در پنجرهٔ context مدل جا نمی‌شود. خودِ این رد هزینه‌ای ندارد (ولی OCRِ پلاگین file-parser که پیش از آن اجرا شده، درخواست جداگانه‌ای بوده و حساب شده). کوتاهش کنید یا transforms: ["middle-out"] بفرستید.
file_parser_failed / file_parser_unavailable / too_many_files4xx / 502پلاگین file-parser: سند خوانده نشد یا متنی از آن درنیامد (با همان وضعیتی که خودِ OCR داد)، پلاگین روی این سرویس پیکربندی نشده، یا بیش از ۴ PDF در یک درخواست.
file_parser_daily_pages429پلن رایگان سقف روزانهٔ صفحات file-parser را پر کرده؛ Retry-After تا نیمه‌شب تهران.
file_not_found400file_id‌ای که درخواست نام برده برای این کلید پیدا نشد: وجود ندارد، مال حساب دیگری است یا پاک شده. چیزی شارژ نشده.
unsupported_parameter400در tools یا tool_choice نوع ابزاری آمده که اینجا اجرا نمی‌شود (متن خطا نامش را می‌گوید). فقط ابزار function پذیرفته می‌شود، و جست‌وجو، خواندن صفحه و تاریخِ خودمان.
invalid_plugins400نام پلاگین یا transform ناشناخته است. مجازها: web، response-healing، file-parser و middle-out.
model_not_found404شناسهٔ مدل ناشناخته است — یا وجود ندارد یا منتشر نشده. برای iranrouter/auto: tier ناشناخته یا tierای که فعلاً مدلی ندارد.
rate_limit_rpm / rph / rpd / tpm / account_rpm429سقف نرخ همان پنجره پر شده. به retry-after احترام بگذارید.
guardrail_rate_limited / guardrail_concurrency_limited429یک گاردریل سازمان (برای این عضو، این Workspace یا کل سازمان) سقف درخواست در دقیقه یا درخواست همزمان دارد و پر است. هدر X-IranRouter-Guardrail نامش را می‌دهد؛ retry-after تا دقیقهٔ بعد، یا یک ثانیه.
concurrency_limit_exceeded429این کلید به سقف درخواست همزمانِ خودش رسیده (در داشبورد، ویرایش کلید). یکی که تمام شود جا باز می‌شود؛ retry-after یک ثانیه است.
key_daily_token_budget_reached429سقف روزانهٔ توکن کلید. نیمه‌شب تهران بازنشانی می‌شود.
key_daily_budget_reached429سقف روزانهٔ ریالی کلید.
free_daily_limit429سقف روزانهٔ پلن رایگان.
pack_limit_exceeded429سقف درخواست یک پک مدل برای حساب شما پر شده است.
global_throttle429محدودیت موقت کل پلتفرم در زمان اوج.
no_capacity503فعلاً مسیر سالمی برای این مدل نیست. کمی بعد دوباره تلاش کنید.
gateway_paused503سرویس در حالت تعمیرات است.
pricing_unavailable503نرخ فعالی برای قیمت‌گذاری نیست؛ ما ترجیح می‌دهیم کور شارژ نکنیم.
byok_rate_limited429سقف نرخی که ما روی کلید اختصاصی (BYOK) شما گذاشته‌ایم پر شده.
server_overloaded / load_shed503ظرفیت هم‌زمانی پر است، یا در اوج بار ترافیک این پلن موقتاً کنار گذاشته می‌شود. به retry-after احترام بگذارید.
model_in_maintenance503مدل موقتاً از سرویس خارج است.

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

codeHTTPمعنی
request_timeout408 / 503۴۰۸: آپلود فایل متوقف شد (۶۰ ثانیه هیچ بایتی نرسید) یا خیلی کند بود (بعد از ۳۰ ثانیهٔ اول، کمتر از ۴ کیلوبایت در ثانیه). با اتصال پایدارتر دوباره بفرستید. ۵۰۳: وقت درخواستی که ابزارهای سمت سرور ما (جست‌وجو، خواندن صفحه) را به کار می‌برد تمام شد؛ دورهایی که پیش از آن تمام شده‌اند مثل همیشه حساب شده‌اند. دوباره بفرستید، یا در یک درخواست کار کمتری بخواهید.
unsupported_file_type415این نوع فایل پذیرفته نیست. نوع از روی خود بایت‌ها تشخیص داده می‌شود، نه از نام یا content-type. پذیرفته‌ها: سند (PDF، Word، Excel، PowerPoint)، تصویر، صدا یا متن (JSON، JSONL، CSV، Markdown، متن ساده).
video_not_ready409ویدئو هنوز آماده نیست. GET /v1/videos/{id} را تا completed دنبال کنید و بعد محتوا را بگیرید.
video_failed410کار ساخت ویدئو کامل نشد (شکست خورد یا منقضی شد) و فایلی ندارد.
page_unavailable502‎/v1/fetch نتوانست صفحه را بخواند. هزینه‌ای ندارد.
idempotency_in_flight409درخواست اصلی با همین Idempotency-Key هنوز در حال اجراست.
idempotency_completed_unreplayable409درخواست اصلی کامل شد ولی پاسخش برای بازپخش خیلی بزرگ بود.
idempotency_key_reused422این Idempotency-Key قبلاً برای درخواست دیگری به کار رفته؛ برای درخواست تازه کلید تازه بفرستید.
model_sunset410مدل منسوخ شده و تاریخ خاموشی‌اش گذشته؛ به جانشین (هدر X-IranRouter-Successor) مهاجرت کنید.
payload_too_large413بدنه یا فایل از سقف حجم بزرگ‌تر است.
upstream_error:*502بالادست پس از همهٔ تلاش‌ها شکست خورد؛ پسوند نوع خطا را می‌گوید. چیزی شارژ نشده.

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

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

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

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

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