خطاهای API

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

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

These general request-level error codes correspond to standard HTTP status codes. Use the code field in your application logic to handle errors programmatically.

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

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

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

کد توضیحات
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 تعاملات مراجعه کنید.

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