خطاهای API

این صفحه مرجعی برای تمام کدهای خطای Interactions API ارائه می‌دهد، قالب پاسخ خطا را شرح می‌دهد و توضیح می‌دهد که چگونه API خطاها را برای انواع مختلف درخواست ارائه می‌دهد.

کدهای خطای استاندارد API

این کدهای خطای عمومی در سطح درخواست، مشابه کدهای وضعیت استاندارد HTTP هستند. از فیلد code در منطق برنامه خود برای مدیریت خطاها به صورت برنامه‌نویسی استفاده کنید.

کد وضعیت HTTP توضیحات اقدام توصیه شده
invalid_request درخواست بد ۴۰۰ درخواست ناقص است یا شامل پارامترهای نامعتبر است. ورودی‌های خود را با مرجع API بررسی کنید.
parameter_unknown درخواست بد ۴۰۰ درخواست شامل یک پارامتر ناشناخته است. پارامتر ناشناخته را حذف کنید و دوباره امتحان کنید.
authentication ۴۰۱ غیرمجاز کلید API موجود نیست یا نامعتبر است. کلید API خود را تأیید کنید.
permission_denied ۴۰۳ ممنوعه کلید API شما مجوز دسترسی به این منبع را ندارد. مجوزهای کلید API و دسترسی به پروژه خود را بررسی کنید.
not_found ۴۰۴ یافت نشد منبع مورد نظر یافت نشد. مسیر منبع و پارامترها را تأیید کنید.
model_not_found ۴۰۴ یافت نشد مدل مورد نظر یافت نشد. نام مدل را تأیید کنید یا به مدل دیگری برگردید.
rate_limit_exceeded 429 درخواست‌های بیش از حد شما از محدودیت درخواست یا توکن در هر دقیقه یا هر ثانیه فراتر رفته‌اید. صبر کنید و با backoff نمایی دوباره امتحان کنید.
quota_exceeded 429 درخواست‌های بیش از حد شما از سهمیه روزانه خود فراتر رفته‌اید. صبر کنید تا سهمیه مجدداً تنظیم شود یا درخواست افزایش سهمیه دهید.
cancelled ۴۹۹ درخواست بسته شدن حساب کاربری مشتری درخواست را قبل از تکمیل لغو کرد. هیچ اقدامی لازم نیست. این معمولاً به این معنی است که کلاینت قطع شده است.
api_error خطای داخلی سرور ۵۰۰ خطای غیرمنتظره‌ای در سرور رخ داده است. درخواست را دوباره امتحان کنید. اگر همچنان ادامه داشت، با پشتیبانی تماس بگیرید.
service_unavailable سرویس ۵۰۳ در دسترس نیست سرویس موقتاً دچار اضافه بار یا قطعی است. صبر کنید و با backoff نمایی دوباره امتحان کنید.

تولید کدهای مسدود شده

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

کد توضیحات
safety نقض ایمنی (محتوای مضر) درخواست را مسدود کرد.
recitation محدودیت‌های حق نشر یا بازخوانی، درخواست را مسدود کرد.
language یک زبان پشتیبانی نشده درخواست را مسدود کرد.
prohibited_content دستورالعمل‌های محتوای ممنوعه، درخواست را مسدود کرد.
spii محدودیت‌های مربوط به اطلاعات شخصی حساس، درخواست را مسدود کرد.
blocklist شرایط ممنوعه در لیست سیاه، درخواست را مسدود کرد.
image_safety نقض ایمنی مانع از تولید تصویر شد.
image_prohibited_content دستورالعمل‌های محتوای ممنوعه، تولید تصویر را مسدود کرد.
image_recitation محدودیت‌های حق نشر یا بازخوانی، تولید تصویر را مسدود کرده است.
image_other دلایل نامشخصی مانع از تولید تصویر شد.
content_blocked یک دلیل نامشخص از سیاست، درخواست را مسدود کرد.

کدهای خطای تولید

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

کد توضیحات
malformed_function_call مدل یک فراخوانی تابع ایجاد کرد که قابل تجزیه نبود.
malformed_tool_call این مدل یک فراخوانی ابزار تولید کرد که قابل تجزیه نبود.
unexpected_tool_call مدل، ابزاری را فراخوانی کرد که در درخواست اعلام نشده بود.
no_image مدل قادر به تولید تصویر نبود.
too_many_tool_calls این مدل، فراخوانی‌های ابزار بیشتری نسبت به حد مجاز ایجاد کرد.
missing_thought_signature پاسخ فاقد امضای فکری لازم است.

قالب پاسخ خطا

تمام خطاهای API مربوط به Interactions یک شیء error حاوی یک code و message را برمی‌گردانند. برای مثال، ارسال یک نوع ابزار پشتیبانی نشده، خروجی زیر را می‌دهد:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
میدان نوع توضیحات
code رشته یک کد خطای قابل خواندن توسط ماشین در snake_case .
message رشته توضیحی قابل فهم برای انسان از مشکل پیش آمده.

نحوه ارسال خطاها

بسته به اینکه درخواست شما استاندارد HTTP باشد یا درخواست استریمینگ (SSE)، API خطاها را به طور متفاوتی نمایش می‌دهد.

درخواست‌های استاندارد HTTP

برای درخواست‌های استاندارد (غیر استریمینگ)، API کد وضعیت پاسخ HTTP (مانند 400 Bad Request ، 401 Unauthorized یا 429 Too Many Requests ) را تنظیم می‌کند و یک شیء error را در بدنه پاسخ JSON برمی‌گرداند:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

درخواست‌های استریمینگ (SSE)

برای درخواست‌های استریم ( stream: true )، API رویدادهای خطا را از طریق استریم رویدادهای ارسالی از سرور (SSE) با event_type " برابر با "error" ارسال می‌کند. فیلد error شامل همان code و ساختار message است:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

برای مشاهده‌ی طرح کامل رویداد SSE، به مرجع API تعاملات مراجعه کنید.

قدم بعدی چیست؟