شروع کار

خطاها

قالب دقیق خطا در /v1، فهرست وضعیت‌ها و کدها و اینکه کدام خطا را باید دوباره فرستاد.

قالب خطا

خطاهای /v1 به قالب OpenAI برمی‌گردند:

json
{
  "error": {
    "message": "The model 'openai/unknown' does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model",
    "request_id": "6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10"
  }
}
  • message: متن انگلیسی برای لاگ. برای نشان دادن به کاربر نهایی مناسب نیست.
  • type: دسته‌ی خطا. مقدارهای ممکن invalid_request_error، authentication_error، insufficient_quota، permission_error، rate_limit_error، guardrail_error و api_error هستند. در خطای 429 ناشی از rate_limit_exceeded به‌جای این‌ها requests یا tokens می‌آید، یعنی کدام پنجره پر شده.
  • code: شناسه‌ی پایدار خطا. منطق برنامه را روی code بنویسید، نه روی message.
  • param: پارامتر مشکل‌دار، یا null.
  • request_id: شناسه‌ی درخواست. همان در سرآیند x-request-id هم هست. برای پشتیبانی همین را بفرستید.
  • details: فقط در بعضی خطاها. در 402 مقدار required و available (اعتبار) را دارد.

وضعیت 499 (بسته شدن اتصال توسط کلاینت) هیچ‌وقت به شما نمی‌رسد، چون کلاینت رفته است.

قالب Anthropic و Gemini

روی /v1/messages خطا به قالب Anthropic می‌آید: {"type": "error", "error": {"type", "message"}, "request_id"}. وضعیت 446 (مسدود شدن توسط قاعده‌ی نگهبان) در آن 400 و وضعیت 503 برابر 529 می‌شود. روی /v1beta خطا به قالب Google است: {"error": {"code", "message", "status"}} و 446 به 400 تبدیل می‌شود. کدهای وان ای آی در این دو قالب نیستند، پس تصمیم‌گیری را روی وضعیت HTTP بگذارید.

وضعیت‌ها و کدها

وضعیتکدمعنادوباره بفرستم؟
400invalid_requestبدنه با طرح درخواست نمی‌خواند. param نام فیلد را می‌دهد.خیر، درخواست را اصلاح کنید
400invalid_jsonبدنه JSON معتبر نیستخیر
400context_length_exceededورودی از پنجره‌ی متن مدل بلندتر استخیر، ورودی را کوتاه کنید
400model_kind_mismatchنوع مدل با مسیر نمی‌خواند (مثلاً مدل تصویر در چت)خیر
400provider_invalid_requestمدل پارامترها یا پیام‌ها را نپذیرفتخیر
400invalid_image_urlتصویری که در درخواست آمده خوانده نشدخیر
400provider_model_not_foundمدل فعلاً از سمت سرویس بالادستی در دسترس نیستبعداً، یا مدل دیگر
400invalid_config، config_not_foundمقدار سرآیند x-1ai-config معتبر نیست یا پیدا نشدخیر
400no_routable_targetمدل الان هیچ مسیر سالمی نداردبعد از چند ثانیه
401invalid_api_keyکلید نامعتبر یا غیرفعال استخیر. احراز هویت
402insufficient_creditsاعتبار کافی نیستفقط بعد از شارژ
402key_cap_reachedسقف ماهانه‌ی این کلید پر شدهبعد از تغییر سقف یا ماه بعد
402member_cap_reachedسقف ماهانه‌ی شما در فضای کاری تیمی پر شدهخیر
402model_price_missingقیمت این مدل هنوز تعیین نشدهخیر
403model_not_allowedکلید اجازه‌ی استفاده از این مدل را نداردخیر
403model_not_available_for_tierمدل برای سطح API شما باز نیستخیر
404model_not_foundمدل وجود ندارد یا به آن دسترسی نداریدخیر
404not_foundمسیر یا متد ناشناخته استخیر
413request_too_largeبدنه از حد مجاز بزرگ‌تر است (۲۵ مگابایت)خیر
413file_too_largeفایل آپلودی از ۲۵ مگابایت بزرگ‌تر استخیر
429rate_limit_exceededسقف درخواست یا توکن پر شده. سرآیند retry-after را دارد.بله، بعد از retry-after
429budget_exceededیک بودجه‌ی تعریف‌شده پر شدهخیر، تا پایان دوره یا تغییر بودجه
429provider_rate_limit_exceededسرویس بالادستی موقتاً کند کرده استبله، با تأخیر
446guardrail_deniedیک قاعده‌ی نگهبان درخواست یا پاسخ را مسدود کردخیر
500internal_errorخطای غیرمنتظره در دروازهبله، با تأخیر
502provider_connection_error، provider_api_error، provider_authentication_errorسرویس بالادستی در دسترس نبود یا خطا دادبله، با تأخیر
503provider_service_unavailableسرویس بالادستی موقتاً در دسترس نیستبله، با تأخیر
504provider_timeoutسرویس بالادستی به‌موقع جواب ندادبله، با تأخیر

کدام را دوباره بفرستم

بله: 429 با rate_limit_exceeded یا provider_rate_limit_exceeded، و 500، 502، 503، 504. با تأخیر نمایی و کمی تصادف دوباره بفرستید و اگر retry-after آمده، همان را رعایت کنید. دروازه خودش پیش از رسیدن خطا به شما مسیر بعدی را امتحان می‌کند (پایداری)، پس خطای 5xx یعنی چند مسیر شکست خورده‌اند.

خیر: همه‌ی 4xx دیگر. تکرار همان درخواست همان خطا را می‌دهد. 402 با شارژ حل می‌شود و 400 با اصلاح درخواست.

درخواست‌های ناموفقی که پیش از اجرای مدل رد شدند یا خطای سرویس بالادستی دادند، اعتباری کم نمی‌کنند.

خطا در میانه‌ی استریم

اگر استریم پس از ارسال اولین بایت قطع شود، وضعیت HTTP دیگر قابل تغییر نیست. خطا به شکل یک فریم داده می‌آید و بعد از آن [DONE]. استریم را ببینید.

صفحه‌های مرتبط