۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مستندات API

مرجع خطاهای API: قالب پاسخ و همهٔ کدها

هر خطایی که خود دروازه برمی‌گرداند یک بدنهٔ JSON با error.message، error.type و بیشتر وقت‌ها error.code دارد. برنامه‌ات را روی code بنویس، نه روی متن پیام. درخواست ناموفق هزینه‌ای ندارد. هر پاسخ یک هدر X-Request-Id دارد که برای پیگیری به پشتیبانی می‌دهی.

آخرین به‌روزرسانی:

فهرست مستندات

خطاها · ۱

قالب پاسخ خطا

json
{
  "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 ردیف آن تماس در گزارش مصرف و مرجع تراکنش کیف پولش است. وقتی به پشتیبانی پیام می‌دهی همین را بفرست (متادیتای پاسخ).

http
X-Request-Id: gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA

خطاها · ۳

همهٔ کدهای خطا

کدهای خطای دروازه
وضعیتکدکِی برمی‌گرددچه کار کنی
400invalid_requestبدنهٔ درخواست خوانده نمی‌شود، فیلد لازمی (مثل model یا در مسیر Anthropic max_tokens) نیست، یا فیلدی فرستاده‌ای که این مسیر نمی‌پذیرد (مثل service_tier). در API حساب: from، to یا request_id که خوانده نمی‌شود، یا بازهٔ خروجی CSV بلندتر از سقف؛ آن‌جا param نام پارامتر را می‌گوید.پیام خطا می‌گوید کدام فیلد؛ درخواست را اصلاح کن (API حساب).
400hosted_tool_unmeteredابزار سمت سروری خواسته‌ای که هنوز قیمت‌گذاری نشده (مثل code_interpreter یا file_search در Responses، یا code_execution در Anthropic).آن ابزار را بردار. فهرست ابزارهای مجاز در فراخوانی تابع است.
400search_not_pricedجست‌وجوی وب را روی مدلی خواسته‌ای که نرخ جست‌وجو ندارد.مدل دیگری انتخاب کن یا ابزار جست‌وجو را بردار.
400path_unmeteredbackground: true در /v1/responses، یا stream: true در ساخت تصویر.همان درخواست را بدون آن فیلد بفرست.
400model_not_supportedمدلی که برای تماس صوتی زنده خواسته‌ای در فهرست مدل‌های Realtime نیست.یکی از مدل‌های صوت زنده را انتخاب کن.
400offer_request_refusedدرخواست به یک مدل «پیشنهاد ویژه» پذیرفته نشد.درخواست را ساده‌تر کن یا مدل معمولی همان خانواده را صدا بزن.
400batch_file_invalidفایل ورودی پردازش دسته‌ای (POST /v1/files) سطر نادرستی دارد: line شمارهٔ اولین سطر نادرست است و reason علت آن.آن سطر را درست کن و کل فایل را دوباره بارگذاری کن (قواعد فایل ورودی).
401missing_api_keyکلیدی در Authorization، x-api-key یا x-goog-api-key فرستاده نشده.کلید را در هدر بفرست (احراز هویت). کلید در نشانی (?key=) خوانده نمی‌شود.
401invalid_api_keyکلیدی که 1xAi نمی‌شناسد.کلید را از داشبورد دوباره کپی کن یا کلید تازه بساز.
401account_disabledکلید شناخته شده ولی حساب آن غیرفعال است.به پشتیبانی پیام بده.
401key_revokedکلید باطل یا منقضی شده، یا فضای کاری یا شرکت آن غیرفعال است.کلید تازه بساز.
401key_cappedکلید به سقف خرج خودش رسیده و باطل شده است.کلید تازه با سقف تازه بساز (سقف خرج).
401workspace_limitسقف ماهانهٔ فضای کاری یا عضو پر شده است.تا ماه بعد صبر کن یا سقف را بالا ببر (تیم‌ها و بودجه‌ها).
402insufficient_balanceاعتبار حساب برای پرامپت به‌علاوهٔ یک توکن خروجی (یا برای هزینهٔ ثابت تصویر، صدا و ویدیو) کافی نیست، یا دسته‌ای از پیام‌ها با اعتبار صفر یا منفی فرستاده شده. یا کیف پول کفاف رزرو یک دستهٔ OpenAI را نمی‌دهد (با estimate_toman، required_toman و available_toman).حساب را شارژ کن؛ تماس‌های بعدی بلافاصله پس از پرداخت موفق کار می‌کنند.
402plan_media_usedتماس رسانه‌ای (تصویر، تبدیل صدا به متن، خواندن متن با صدا، ویدیو یا موسیقی) روی حسابی با پلن چت پولی که سهم رسانهٔ پلنش در این دوره تمام شده: از این پس رسانه از کیف پول پرداخت می‌شود و کیف پول کفاف این تماس را نمی‌دهد. تماس‌های متنی همچنان از اعتبار پلن پرداخت می‌شوند.کیف پول را شارژ کن؛ تماس‌های رسانه‌ای بلافاصله پس از پرداخت موفق کار می‌کنند.
402model_not_pricedاین مدل در فهرست قیمت ما نیست. مدل بی‌قیمت رد می‌شود و هرگز رایگان اجرا نمی‌شود.نام مدل را با GET /v1/models بسنج. اگر مدل تازه است به پشتیبانی بگو.
402path_unmeteredمسیری که هنوز نمی‌توانیم هزینه‌اش را دقیق حساب کنیم (مثل Assistants و Uploads در OpenAI‏، Files با purpose دیگری جز batch، یا cachedContents در Gemini). Files و Batches در OpenAI فقط برای پردازش دسته‌ای (purpose=batch) کار می‌کنند.فهرست کامل در مسیرهای پشتیبانی‌نشده است؛ پردازش دسته‌ای در پردازش دسته‌ای OpenAI.
402hosted_tool_unmeteredابزار Google Maps در Gemini، که جدا قیمت‌گذاری می‌شود.به جای آن از grounding با Google Search استفاده کن.
402key_cappedرزرو یک دستهٔ OpenAI از سقف خرج کلید می‌گذرد؛ پاسخ cap_toman، spent_toman و required_toman را دارد. کلید باطل نمی‌شود.سقف را بالا ببر یا سقف خروجی سطرهای فایل را کمتر کن تا رزرو کوچک‌تر شود (رزرو دسته).
402workspace_limitرزرو یک دستهٔ OpenAI زیر سقف ماهانهٔ فضای کاری یا عضو جا ندارد.سقف را بالا ببر یا سقف خروجی سطرهای فایل را کمتر کن تا رزرو کوچک‌تر شود (رزرو دسته).
403feature_disabledحساب نوجوانی که والد آن ساخت تصویر، ویدیو یا تماس صوتی را خاموش کرده یا ساعت آرام گذاشته است.تنظیم والد باید عوض شود.
403forbiddenکلید فضای کاری شرکت GET /v1/wallet/transactions یا GET /v1/sla/credits را خواسته؛ ریز تراکنش‌ها و اعتبارهای جبرانی مال کل شرکت است.اعتبار قابل خرج را از GET /v1/wallet/summary بخوان؛ ریز تراکنش‌ها در داشبورد شرکت است (API حساب).
403key_ip_not_allowedنشانی فرستنده در فهرست نشانی‌های کلید نیست.محدودیت‌های کلید را ببین (محدودیت‌های کلید).
403key_scope_deniedمسیر بیرون از دامنهٔ دسترسی کلید است.محدودیت‌های کلید را ببین (محدودیت‌های کلید).
403key_model_not_allowedمدل در فهرست مدل‌های کلید نیست.محدودیت‌های کلید را ببین (محدودیت‌های کلید).
404path_not_foundمسیر وجود ندارد یا از راه 1xAi در دسترس نیست؛ همچنین هر مسیر یا روش ناشناخته زیر /v1/usage، /v1/wallet و /v1/keys، فهرست دسته‌های پیام (GET /anthropic/v1/messages/batches)، و فهرستی که سازنده از اشیای نگه‌داشته‌اش می‌دهد (مثل GET /v1/videos، یا فهرست operations، files، interactions و cachedContents در Gemini)، برای هر کلیدی.نشانی و روش HTTP را با مستندات بسنج.
404not_foundشناسه‌ای که خواسته‌ای (یک کلید، یک کار ویدیو یا Midjourney، یک دستهٔ پیام، یا شیئی که سازنده برای تماسی نگه می‌دارد: یک operation، فایل یا interaction در Gemini، یا یک ویدیو) پیدا نشد یا با این کلید در دسترس نیست. شیئی که حساب یا فضای کاری دیگری ساخته همین پاسخ را می‌گیرد. دسته یا فایل پردازش دسته‌ای OpenAI هم همین‌طور، و فایلی که خودت پاکش کرده‌ای.شناسه و کلید را بسنج؛ هر شیء با کلیدهای همان حساب، و در فضای کاری شرکت با کلیدهای همان فضای کاری، در دسترس است (دسته‌های پیام).
404not_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).
404file_expiredدورهٔ نگهداری یک فایل پردازش دسته‌ای (۱ روز پس از تسویهٔ دسته) تمام شده و از OpenAI پاک شده است.خروجی هر دسته را در همان مدت دانلود کن (نگهداری و حذف).
409batch_not_settledفایل خروجی یا خطای یک دسته را پیش از تسویهٔ هزینهٔ دسته پاک کرده‌ای.چند دقیقه بعد دوباره پاک کن؛ دسته معمولاً چند دقیقه پس از پایانش تسویه می‌شود.
410model_retiredسازنده این مدل را بازنشسته کرده است.مدل جایگزین را از فهرست مدل‌ها انتخاب کن.
413request_too_largeبدنهٔ درخواست از ۲۵ مگابایت بزرگ‌تر است. بدنهٔ بزرگ‌تر از ۲۶ مگابایت پیش از رسیدن به دروازه رد می‌شود، با همین پاسخ.فایل را کوچک‌تر یا تکه‌تکه بفرست. base64 حجم فایل را حدود یک‌سوم بیشتر می‌کند.
413batch_file_too_largeفایل ورودی پردازش دسته‌ای بزرگ‌تر از ۲۵ مگابایت است.فایل را به چند فایل کوچک‌تر تقسیم کن و برای هر کدام دستهٔ جدا بساز (سقف‌ها).
415unsupported_typeمسیر JSON می‌خواهد و Content-Type چیز دیگری است.Content-Type: application/json بفرست.
429rate_limit_exceededکلید از سقف خودش (به‌طور پیش‌فرض ۱٬۰۰۰ درخواست در دقیقه) گذشته است.به اندازهٔ Retry-After صبر کن (محدودیت نرخ).
429upstream_capacityسازندهٔ مدل شلوغ است و درخواست را نپذیرفت؛ سقف کلید تو نیست. در POST /v1/batches یعنی صف دسته‌ای ما نزد OpenAI پر است.کمی بعد دوباره بفرست یا مدل دیگری انتخاب کن.
429batch_limitیکی از سقف‌های پردازش دسته‌ای حساب: دسته‌های تسویه‌نشده، جمع تخمین آن‌ها، درخواست‌های روزانه، بارگذاری هم‌زمان، یا تعداد و حجم فایل‌های نگه‌داشته‌شده نزد OpenAI. پاسخ سقف و مقدار فعلی را می‌گوید.صبر کن تا دسته‌ای تسویه شود، یا فایل‌هایی را که لازم نداری پاک کن (سقف‌ها).
429export_in_progressخروجی CSV دیگری برای همین حساب (یا همین فضای کاری) در جریان است.به اندازهٔ Retry-After صبر کن (خروجی CSV).
429rate_limitedبیش از ۶ خروجی CSV در یک دقیقه.به اندازهٔ Retry-After صبر کن.
429daily_limitحساب نوجوان به سقف خرج روزانه‌ای که والد گذاشته رسیده است.از فردا دوباره کار می‌کند.
500internalخطا در سمت ما.دوباره بفرست؛ اگر تکرار شد شناسهٔ درخواست را به پشتیبانی بده.
502upstream_errorارتباط با سازندهٔ مدل برقرار نشد یا پاسخش خوانده نشد.دوباره بفرست. هزینه‌ای حساب نشده است.
503upstream_unavailableسازندهٔ این مدل الان از راه ما در دسترس نیست. به کلید یا اعتبار تو ربطی ندارد.چند دقیقه بعد دوباره بفرست یا مدل دیگری انتخاب کن؛ وضعیت سرویس را ببین.
503usage_search_timeoutجست‌وجوی q در گزارش مصرف بیش از ۸ ثانیه طول کشید.بازه را با from و to کوتاه کن، یا یک تماس را با request_id پیدا کن.
503offer_unavailableظرفیت یک مدل «پیشنهاد ویژه» الان پر است. هدر Retry-After دارد.پس از آن مدت دوباره بفرست یا مدل معمولی را صدا بزن.
504upstream_errorسازندهٔ مدل در ۱۰ دقیقه پاسخی نداد.اگر هیچ پاسخی نرسیده، هزینه‌ای حساب نشده است. درخواست را کوچک‌تر کن یا با stream بفرست.

خطاها · ۴

خطاهایی که از سازندهٔ مدل می‌آیند

  • خطایی که سازندهٔ مدل دربارهٔ خود درخواست می‌دهد (پارامتر نادرست، پرامپت بلندتر از پنجرهٔ مدل، محتوای ردشده) با همان وضعیت و همان بدنهٔ سازنده به تو می‌رسد.
  • روی /anthropic و /gemini بدنهٔ خطای سازنده به شکل خود او است ({"type":"error",…} در Anthropic، {"error":{"status":…}} در Google).
  • اگر مشکل از حساب ما نزد سازنده باشد، آن را به تو نسبت نمی‌دهیم: پاسخ 503 با کد upstream_unavailable می‌گیری، نه 401 یا 402.
  • اگر نام مدل نزد سازنده شناخته نشود، پاسخ فیلد suggested_model با نزدیک‌ترین مدل در دسترس را دارد.

خطاها · ۵

هزینهٔ درخواست ناموفق

درخواستی که با خطا تمام شود در گزارش مصرف ثبت می‌شود و هزینه‌ای ندارد. تنها استثنا پاسخی است که بخشی از آن رسیده و بعد قطع شده: همان بخش حساب می‌شود. جزئیات در صورت‌حساب است.