مرجع خطاهای API: قالب پاسخ و همهٔ کدها
هر خطایی که خود دروازه برمیگرداند یک بدنهٔ JSON با error.message، error.type و بیشتر وقتها error.code دارد. برنامهات را روی code بنویس، نه روی متن پیام. درخواست ناموفق هزینهای ندارد. هر پاسخ یک هدر X-Request-Id دارد که برای پیگیری به پشتیبانی میدهی.
آخرین بهروزرسانی:
فهرست مستندات
مسیرهای API
حساب، کلید و تیم
خطاها · ۱
قالب پاسخ خطا
{
"error": {
"message": "Insufficient balance. Please top up your account.",
"type": "api_error",
"code": "insufficient_balance"
}
}codeکد ماشینی خطاست و ثابت میماند و هر خطای جدولهای زیر یکی دارد. هر401دروازه کد دارد، و413بدنهٔ بزرگتر از سقف هم کدrequest_too_largeدارد.- بعضی خطاهای API حساب فیلد
paramهم دارند: نام پارامتری که خوانده نشد. typeبرای خطاهای دروازهapi_errorاست، جز سقف نرخ کهrate_limit_exceededاست.messageفارسی است؛ با هدرAccept-Language: enانگلیسی میشود. چند پیام فقط فارسیاند، پس متن پیام را در برنامه مقایسه نکن.- همین قالب روی
/anthropicو/geminiهم برای خطاهای خود دروازه به کار میرود.
خطاها · ۲
شناسهٔ درخواست
هر پاسخ روی /v1، /anthropic و /gemini، موفق یا ناموفق، هدر X-Request-Id دارد (با gw_ شروع میشود). همین شناسه request_id ردیف آن تماس در گزارش مصرف و مرجع تراکنش کیف پولش است. وقتی به پشتیبانی پیام میدهی همین را بفرست (متادیتای پاسخ).
X-Request-Id: gw_01JD3Z5T8Q0V6W4M2K9R7N1PXAخطاها · ۳
همهٔ کدهای خطا
| وضعیت | کد | کِی برمیگردد | چه کار کنی |
|---|---|---|---|
400 | invalid_request | بدنهٔ درخواست خوانده نمیشود، فیلد لازمی (مثل model یا در مسیر Anthropic max_tokens) نیست، یا فیلدی فرستادهای که این مسیر نمیپذیرد (مثل service_tier). در API حساب: from، to یا request_id که خوانده نمیشود، یا بازهٔ خروجی CSV بلندتر از سقف؛ آنجا param نام پارامتر را میگوید. | پیام خطا میگوید کدام فیلد؛ درخواست را اصلاح کن (API حساب). |
400 | hosted_tool_unmetered | ابزار سمت سروری خواستهای که هنوز قیمتگذاری نشده (مثل code_interpreter یا file_search در Responses، یا code_execution در Anthropic). | آن ابزار را بردار. فهرست ابزارهای مجاز در فراخوانی تابع است. |
400 | search_not_priced | جستوجوی وب را روی مدلی خواستهای که نرخ جستوجو ندارد. | مدل دیگری انتخاب کن یا ابزار جستوجو را بردار. |
400 | path_unmetered | background: true در /v1/responses، یا stream: true در ساخت تصویر. | همان درخواست را بدون آن فیلد بفرست. |
400 | model_not_supported | مدلی که برای تماس صوتی زنده خواستهای در فهرست مدلهای Realtime نیست. | یکی از مدلهای صوت زنده را انتخاب کن. |
400 | offer_request_refused | درخواست به یک مدل «پیشنهاد ویژه» پذیرفته نشد. | درخواست را سادهتر کن یا مدل معمولی همان خانواده را صدا بزن. |
400 | batch_file_invalid | فایل ورودی پردازش دستهای (POST /v1/files) سطر نادرستی دارد: line شمارهٔ اولین سطر نادرست است و reason علت آن. | آن سطر را درست کن و کل فایل را دوباره بارگذاری کن (قواعد فایل ورودی). |
401 | missing_api_key | کلیدی در Authorization، x-api-key یا x-goog-api-key فرستاده نشده. | کلید را در هدر بفرست (احراز هویت). کلید در نشانی (?key=) خوانده نمیشود. |
401 | invalid_api_key | کلیدی که 1xAi نمیشناسد. | کلید را از داشبورد دوباره کپی کن یا کلید تازه بساز. |
401 | account_disabled | کلید شناخته شده ولی حساب آن غیرفعال است. | به پشتیبانی پیام بده. |
401 | key_revoked | کلید باطل یا منقضی شده، یا فضای کاری یا شرکت آن غیرفعال است. | کلید تازه بساز. |
401 | key_capped | کلید به سقف خرج خودش رسیده و باطل شده است. | کلید تازه با سقف تازه بساز (سقف خرج). |
401 | workspace_limit | سقف ماهانهٔ فضای کاری یا عضو پر شده است. | تا ماه بعد صبر کن یا سقف را بالا ببر (تیمها و بودجهها). |
402 | insufficient_balance | اعتبار حساب برای پرامپت بهعلاوهٔ یک توکن خروجی (یا برای هزینهٔ ثابت تصویر، صدا و ویدیو) کافی نیست، یا دستهای از پیامها با اعتبار صفر یا منفی فرستاده شده. یا کیف پول کفاف رزرو یک دستهٔ OpenAI را نمیدهد (با estimate_toman، required_toman و available_toman). | حساب را شارژ کن؛ تماسهای بعدی بلافاصله پس از پرداخت موفق کار میکنند. |
402 | plan_media_used | تماس رسانهای (تصویر، تبدیل صدا به متن، خواندن متن با صدا، ویدیو یا موسیقی) روی حسابی با پلن چت پولی که سهم رسانهٔ پلنش در این دوره تمام شده: از این پس رسانه از کیف پول پرداخت میشود و کیف پول کفاف این تماس را نمیدهد. تماسهای متنی همچنان از اعتبار پلن پرداخت میشوند. | کیف پول را شارژ کن؛ تماسهای رسانهای بلافاصله پس از پرداخت موفق کار میکنند. |
402 | model_not_priced | این مدل در فهرست قیمت ما نیست. مدل بیقیمت رد میشود و هرگز رایگان اجرا نمیشود. | نام مدل را با GET /v1/models بسنج. اگر مدل تازه است به پشتیبانی بگو. |
402 | path_unmetered | مسیری که هنوز نمیتوانیم هزینهاش را دقیق حساب کنیم (مثل Assistants و Uploads در OpenAI، Files با purpose دیگری جز batch، یا cachedContents در Gemini). Files و Batches در OpenAI فقط برای پردازش دستهای (purpose=batch) کار میکنند. | فهرست کامل در مسیرهای پشتیبانینشده است؛ پردازش دستهای در پردازش دستهای OpenAI. |
402 | hosted_tool_unmetered | ابزار Google Maps در Gemini، که جدا قیمتگذاری میشود. | به جای آن از grounding با Google Search استفاده کن. |
402 | key_capped | رزرو یک دستهٔ OpenAI از سقف خرج کلید میگذرد؛ پاسخ cap_toman، spent_toman و required_toman را دارد. کلید باطل نمیشود. | سقف را بالا ببر یا سقف خروجی سطرهای فایل را کمتر کن تا رزرو کوچکتر شود (رزرو دسته). |
402 | workspace_limit | رزرو یک دستهٔ OpenAI زیر سقف ماهانهٔ فضای کاری یا عضو جا ندارد. | سقف را بالا ببر یا سقف خروجی سطرهای فایل را کمتر کن تا رزرو کوچکتر شود (رزرو دسته). |
403 | feature_disabled | حساب نوجوانی که والد آن ساخت تصویر، ویدیو یا تماس صوتی را خاموش کرده یا ساعت آرام گذاشته است. | تنظیم والد باید عوض شود. |
403 | forbidden | کلید فضای کاری شرکت GET /v1/wallet/transactions یا GET /v1/sla/credits را خواسته؛ ریز تراکنشها و اعتبارهای جبرانی مال کل شرکت است. | اعتبار قابل خرج را از GET /v1/wallet/summary بخوان؛ ریز تراکنشها در داشبورد شرکت است (API حساب). |
403 | key_ip_not_allowed | نشانی فرستنده در فهرست نشانیهای کلید نیست. | محدودیتهای کلید را ببین (محدودیتهای کلید). |
403 | key_scope_denied | مسیر بیرون از دامنهٔ دسترسی کلید است. | محدودیتهای کلید را ببین (محدودیتهای کلید). |
403 | key_model_not_allowed | مدل در فهرست مدلهای کلید نیست. | محدودیتهای کلید را ببین (محدودیتهای کلید). |
404 | path_not_found | مسیر وجود ندارد یا از راه 1xAi در دسترس نیست؛ همچنین هر مسیر یا روش ناشناخته زیر /v1/usage، /v1/wallet و /v1/keys، فهرست دستههای پیام (GET /anthropic/v1/messages/batches)، و فهرستی که سازنده از اشیای نگهداشتهاش میدهد (مثل GET /v1/videos، یا فهرست operations، files، interactions و cachedContents در Gemini)، برای هر کلیدی. | نشانی و روش HTTP را با مستندات بسنج. |
404 | not_found | شناسهای که خواستهای (یک کلید، یک کار ویدیو یا Midjourney، یک دستهٔ پیام، یا شیئی که سازنده برای تماسی نگه میدارد: یک operation، فایل یا interaction در Gemini، یا یک ویدیو) پیدا نشد یا با این کلید در دسترس نیست. شیئی که حساب یا فضای کاری دیگری ساخته همین پاسخ را میگیرد. دسته یا فایل پردازش دستهای OpenAI هم همینطور، و فایلی که خودت پاکش کردهای. | شناسه و کلید را بسنج؛ هر شیء با کلیدهای همان حساب، و در فضای کاری شرکت با کلیدهای همان فضای کاری، در دسترس است (دستههای پیام). |
404 | not_found | بدنهٔ درخواست شیئی را نام برده که با این کلید در دسترس نیست: previous_response_id، conversation، prompt.id، یک item_reference یا یک file_id در OpenAI، یک fileUri (یا file_uri)، cachedContent یا previous_interaction_id در Gemini، یا file_id یک منبع فایل در Anthropic. پیش از هر رزرو اعتبار پاسخ داده میشود و هزینهای ندارد. file_id یک فایل پردازش دستهای هم همین پاسخ را میگیرد، حتی با کلید صاحبش: آن فایلها فقط به کار دسته میآیند. | آن شناسه را از بدنه بردار یا محتوا را مستقیم در درخواست بفرست. پاسخها نزد OpenAI ذخیره نمیشوند، پس previous_response_id به کار نمیآید (مسیرهای سازگار با OpenAI). |
404 | file_expired | دورهٔ نگهداری یک فایل پردازش دستهای (۱ روز پس از تسویهٔ دسته) تمام شده و از OpenAI پاک شده است. | خروجی هر دسته را در همان مدت دانلود کن (نگهداری و حذف). |
409 | batch_not_settled | فایل خروجی یا خطای یک دسته را پیش از تسویهٔ هزینهٔ دسته پاک کردهای. | چند دقیقه بعد دوباره پاک کن؛ دسته معمولاً چند دقیقه پس از پایانش تسویه میشود. |
410 | model_retired | سازنده این مدل را بازنشسته کرده است. | مدل جایگزین را از فهرست مدلها انتخاب کن. |
413 | request_too_large | بدنهٔ درخواست از ۲۵ مگابایت بزرگتر است. بدنهٔ بزرگتر از ۲۶ مگابایت پیش از رسیدن به دروازه رد میشود، با همین پاسخ. | فایل را کوچکتر یا تکهتکه بفرست. base64 حجم فایل را حدود یکسوم بیشتر میکند. |
413 | batch_file_too_large | فایل ورودی پردازش دستهای بزرگتر از ۲۵ مگابایت است. | فایل را به چند فایل کوچکتر تقسیم کن و برای هر کدام دستهٔ جدا بساز (سقفها). |
415 | unsupported_type | مسیر JSON میخواهد و Content-Type چیز دیگری است. | Content-Type: application/json بفرست. |
429 | rate_limit_exceeded | کلید از سقف خودش (بهطور پیشفرض ۱٬۰۰۰ درخواست در دقیقه) گذشته است. | به اندازهٔ Retry-After صبر کن (محدودیت نرخ). |
429 | upstream_capacity | سازندهٔ مدل شلوغ است و درخواست را نپذیرفت؛ سقف کلید تو نیست. در POST /v1/batches یعنی صف دستهای ما نزد OpenAI پر است. | کمی بعد دوباره بفرست یا مدل دیگری انتخاب کن. |
429 | batch_limit | یکی از سقفهای پردازش دستهای حساب: دستههای تسویهنشده، جمع تخمین آنها، درخواستهای روزانه، بارگذاری همزمان، یا تعداد و حجم فایلهای نگهداشتهشده نزد OpenAI. پاسخ سقف و مقدار فعلی را میگوید. | صبر کن تا دستهای تسویه شود، یا فایلهایی را که لازم نداری پاک کن (سقفها). |
429 | export_in_progress | خروجی CSV دیگری برای همین حساب (یا همین فضای کاری) در جریان است. | به اندازهٔ Retry-After صبر کن (خروجی CSV). |
429 | rate_limited | بیش از ۶ خروجی CSV در یک دقیقه. | به اندازهٔ Retry-After صبر کن. |
429 | daily_limit | حساب نوجوان به سقف خرج روزانهای که والد گذاشته رسیده است. | از فردا دوباره کار میکند. |
500 | internal | خطا در سمت ما. | دوباره بفرست؛ اگر تکرار شد شناسهٔ درخواست را به پشتیبانی بده. |
502 | upstream_error | ارتباط با سازندهٔ مدل برقرار نشد یا پاسخش خوانده نشد. | دوباره بفرست. هزینهای حساب نشده است. |
503 | upstream_unavailable | سازندهٔ این مدل الان از راه ما در دسترس نیست. به کلید یا اعتبار تو ربطی ندارد. | چند دقیقه بعد دوباره بفرست یا مدل دیگری انتخاب کن؛ وضعیت سرویس را ببین. |
503 | usage_search_timeout | جستوجوی q در گزارش مصرف بیش از ۸ ثانیه طول کشید. | بازه را با from و to کوتاه کن، یا یک تماس را با request_id پیدا کن. |
503 | offer_unavailable | ظرفیت یک مدل «پیشنهاد ویژه» الان پر است. هدر Retry-After دارد. | پس از آن مدت دوباره بفرست یا مدل معمولی را صدا بزن. |
504 | upstream_error | سازندهٔ مدل در ۱۰ دقیقه پاسخی نداد. | اگر هیچ پاسخی نرسیده، هزینهای حساب نشده است. درخواست را کوچکتر کن یا با stream بفرست. |
خطاها · ۴
خطاهایی که از سازندهٔ مدل میآیند
- خطایی که سازندهٔ مدل دربارهٔ خود درخواست میدهد (پارامتر نادرست، پرامپت بلندتر از پنجرهٔ مدل، محتوای ردشده) با همان وضعیت و همان بدنهٔ سازنده به تو میرسد.
- روی
/anthropicو/geminiبدنهٔ خطای سازنده به شکل خود او است ({"type":"error",…}در Anthropic،{"error":{"status":…}}در Google). - اگر مشکل از حساب ما نزد سازنده باشد، آن را به تو نسبت نمیدهیم: پاسخ
503با کدupstream_unavailableمیگیری، نه401یا402. - اگر نام مدل نزد سازنده شناخته نشود، پاسخ فیلد
suggested_modelبا نزدیکترین مدل در دسترس را دارد.
خطاها · ۵
هزینهٔ درخواست ناموفق
درخواستی که با خطا تمام شود در گزارش مصرف ثبت میشود و هزینهای ندارد. تنها استثنا پاسخی است که بخشی از آن رسیده و بعد قطع شده: همان بخش حساب میشود. جزئیات در صورتحساب است.