بدنهٔ درخواست ایراد دارد — پیام دقیقاً میگوید کدام فیلد.
request_exceeds_token_limit
پرامپت + max_tokens از کل سقف توکندردقیقهٔ شما بزرگتر است. این هرگز با تلاش دوباره درست نمیشود: پرامپت را کوتاه کنید یا max_tokens را پایین بیاورید.
streaming_disabled
stream موقتاً غیرفعال است. با 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 میفرستد.
۴۰۴ / ۴۲۹ / ۵۰۳
code
HTTP
معنی
invalid_preset
400
نام پریست فقط حروف کوچک انگلیسی، عدد و خطتیره است.
storage_unavailable
507 / 503
فضای ذخیرهٔ فایل در دسترس نیست: ۵۰۷ هنگام آپلود (گاهی موقت، گاهی چون این سرویس فعلاً فایل نگه نمیدارد — متن خطا میگوید کدام)، ۵۰۳ هنگام خواندن.
preset_not_found
404
پریستی با این شناسه در Workspace این کلید نیست. پریستها به فضای کار تعلق دارند (@preset/شناسه).
context_length_exceeded
400
متن گفتگو حتی با خوشبینانهترین شمارش در پنجرهٔ context مدل جا نمیشود. خودِ این رد هزینهای ندارد (ولی OCRِ پلاگین file-parser که پیش از آن اجرا شده، درخواست جداگانهای بوده و حساب شده). کوتاهش کنید یا transforms: ["middle-out"] بفرستید.
پلاگین file-parser: سند خوانده نشد یا متنی از آن درنیامد (با همان وضعیتی که خودِ OCR داد)، پلاگین روی این سرویس پیکربندی نشده، یا بیش از ۴ PDF در یک درخواست.
file_parser_daily_pages
429
پلن رایگان سقف روزانهٔ صفحات file-parser را پر کرده؛ Retry-After تا نیمهشب تهران.
file_not_found
400
file_idای که درخواست نام برده برای این کلید پیدا نشد: وجود ندارد، مال حساب دیگری است یا پاک شده. چیزی شارژ نشده.
unsupported_parameter
400
در tools یا tool_choice نوع ابزاری آمده که اینجا اجرا نمیشود (متن خطا نامش را میگوید). فقط ابزار function پذیرفته میشود، و جستوجو، خواندن صفحه و تاریخِ خودمان.
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 / account_rpm
429
سقف نرخ همان پنجره پر شده. به retry-after احترام بگذارید.
یک گاردریل سازمان (برای این عضو، این Workspace یا کل سازمان) سقف درخواست در دقیقه یا درخواست همزمان دارد و پر است. هدر X-IranRouter-Guardrail نامش را میدهد؛ retry-after تا دقیقهٔ بعد، یا یک ثانیه.
concurrency_limit_exceeded
429
این کلید به سقف درخواست همزمانِ خودش رسیده (در داشبورد، ویرایش کلید). یکی که تمام شود جا باز میشود؛ retry-after یک ثانیه است.
key_daily_token_budget_reached
429
سقف روزانهٔ توکن کلید. نیمهشب تهران بازنشانی میشود.
key_daily_budget_reached
429
سقف روزانهٔ ریالی کلید.
free_daily_limit
429
سقف روزانهٔ پلن رایگان.
pack_limit_exceeded
429
سقف درخواست یک پک مدل برای حساب شما پر شده است.
global_throttle
429
محدودیت موقت کل پلتفرم در زمان اوج.
no_capacity
503
فعلاً مسیر سالمی برای این مدل نیست. کمی بعد دوباره تلاش کنید.
gateway_paused
503
سرویس در حالت تعمیرات است.
pricing_unavailable
503
نرخ فعالی برای قیمتگذاری نیست؛ ما ترجیح میدهیم کور شارژ نکنیم.
byok_rate_limited
429
سقف نرخی که ما روی کلید اختصاصی (BYOK) شما گذاشتهایم پر شده.
server_overloaded / load_shed
503
ظرفیت همزمانی پر است، یا در اوج بار ترافیک این پلن موقتاً کنار گذاشته میشود. به retry-after احترام بگذارید.
model_in_maintenance
503
مدل موقتاً از سرویس خارج است.
۴۰۸ / ۴۰۹ / ۴۱۰ / ۴۱۳ / ۴۱۵ / ۴۲۲ / ۵۰۲
code
HTTP
معنی
request_timeout
408 / 503
۴۰۸: آپلود فایل متوقف شد (۶۰ ثانیه هیچ بایتی نرسید) یا خیلی کند بود (بعد از ۳۰ ثانیهٔ اول، کمتر از ۴ کیلوبایت در ثانیه). با اتصال پایدارتر دوباره بفرستید. ۵۰۳: وقت درخواستی که ابزارهای سمت سرور ما (جستوجو، خواندن صفحه) را به کار میبرد تمام شد؛ دورهایی که پیش از آن تمام شدهاند مثل همیشه حساب شدهاند. دوباره بفرستید، یا در یک درخواست کار کمتری بخواهید.
unsupported_file_type
415
این نوع فایل پذیرفته نیست. نوع از روی خود بایتها تشخیص داده میشود، نه از نام یا content-type. پذیرفتهها: سند (PDF، Word، Excel، PowerPoint)، تصویر، صدا یا متن (JSON، JSONL، CSV، Markdown، متن ساده).
video_not_ready
409
ویدئو هنوز آماده نیست. GET /v1/videos/{id} را تا completed دنبال کنید و بعد محتوا را بگیرید.
video_failed
410
کار ساخت ویدئو کامل نشد (شکست خورد یا منقضی شد) و فایلی ندارد.
page_unavailable
502
/v1/fetch نتوانست صفحه را بخواند. هزینهای ندارد.
idempotency_in_flight
409
درخواست اصلی با همین Idempotency-Key هنوز در حال اجراست.
idempotency_completed_unreplayable
409
درخواست اصلی کامل شد ولی پاسخش برای بازپخش خیلی بزرگ بود.
idempotency_key_reused
422
این Idempotency-Key قبلاً برای درخواست دیگری به کار رفته؛ برای درخواست تازه کلید تازه بفرستید.
model_sunset
410
مدل منسوخ شده و تاریخ خاموشیاش گذشته؛ به جانشین (هدر X-IranRouter-Successor) مهاجرت کنید.
payload_too_large
413
بدنه یا فایل از سقف حجم بزرگتر است.
upstream_error:*
502
بالادست پس از همهٔ تلاشها شکست خورد؛ پسوند نوع خطا را میگوید. چیزی شارژ نشده.
الگوی تلاش دوباره
کدامها ارزش تلاش دوباره دارند و کدامها نه:
قابل تلاش دوباره: 429 (پس از retry-after), 503 no_capacity, 5xx بالادست — با عقبنشینی نمایی.