این صفحه مرجعی برای همه کدهای خطای Interactions API ارائه می‌دهد، قالب پاسخ خطا را شرح می‌دهد، و توضیح می‌دهد که API چگونه خطاها را برای انواع مختلف درخواست ارائه می‌دهد.
کدهای خطای استاندارد میانای برنامه‌سازی کاربردی
این کدهای خطای عمومی سطح درخواست با کدهای وضعیت استاندارد اچ‌تی‌تی‌پی مطابقت دارند.
از فیلد code در منطق برنامه‌تان برای رسیدگی به خطاها به‌صورت برنامه‌ریزی‌شده استفاده کنید.
| کد | وضعیت HTTP | شرح | اقدام توصیه‌شده |
|---|---|---|---|
invalid_request |
خطای ۴۰۰ - درخواست نامناسب | محموله درخواست قالب نادرستی دارد یا حاوی پارامترهای نامعتبر است. | نحو و پارامترهای درخواستتان را با مرجع میانای برنامه‌سازی کاربردی مطابقت دهید. |
failed_precondition |
خطای ۴۰۰ - درخواست نامناسب | درخواست پردازش نمی‌شود زیرا پیش‌نیازی برآورده نشده است (برای مثال، صورت‌حساب غیرفعال است). | درستی‌سنجی کردن وضعیت صورت‌حساب پروژه یا پیش‌نیازهای حساب. |
out_of_range |
416 Requested Range Not Satisfiable | پارامتر درخواست خارج از محدوده معتبر است. | مقادیر و حدود پارامتر را بررسی کنید. |
parameter_unknown |
خطای ۴۰۰ - درخواست نامناسب | درخواست حاوی پارامتر ناشناخته‌ای است. | پارامتر ناشناخته را بردارید و دوباره امتحان کنید. |
authentication |
خطای ۴۰۱ - غیرمجاز است | کلید میانای برنامه‌سازی کاربردی وجود ندارد، نامعتبر است، یا منقضی شده است. | کلید میانای برنامه‌سازی کاربردی خود را درستی‌سنجی کنید. |
payment_required |
خطای ۴۰۲ - پرداخت لازم است | موجودی اعتبار پیش‌پرداخت شما تمام شده است. | به حساب صورت‌حسابتان اعتبار اضافه کنید یا بار کردن مجدد خودکار را روشن کنید. دوباره امتحان نکنید: تا زمانی که اعتبار اضافه نشود، درخواست موفقیت‌آمیز نخواهد بود. |
permission_denied |
خطای ۴۰۳ - ممنوع است | کلید میانای API شما برای این منبع اجازه ندارد، یا دسترسی API پروژه شما محدود شده است. | اجازه‌های کلید میانای برنامه‌سازی کاربردی، واجدشرایط بودن سطح پروژه، و وضعیت صورت‌حساب را بررسی کنید. عیب‌یابی پروژه محدودشده یا دردسترس‌نبودن را ببینید. |
not_found |
404 یافت نشد | منبع درخواستی پیدا نشد. | مسیر و پارامترهای منبع را درستی‌سنجی کنید. |
model_not_found |
404 یافت نشد | مدل مشخص‌شده پیدا نشد. | نام مدل را درستی‌سنجی کنید یا به مدل دیگری برگردید. |
already_exists |
۴۰۹ تداخل | نهادی که می‌خواستید ایجاد کنید ازقبل وجود دارد. | قبل‌از ایجاد مجدد، بررسی کنید که منبع ازقبل وجود نداشته باشد. |
aborted |
۴۰۹ تداخل | عملیات به‌دلیل تداخل یا ناموفق بودن بررسی همزمانی لغو شد. | درخواست را در سطح برنامه بالاتری تکرار کنید. |
rate_limit_exceeded |
۴۲۹ درخواست‌های بسیار زیاد | از حد مجاز درخواست یا توکن در دقیقه یا ثانیه فراتر رفته‌اید. | صبر کنید و با عقب‌گرد نمایی دوباره امتحان کنید. |
quota_exceeded |
۴۲۹ درخواست‌های بسیار زیاد | از سهمیه روزانه‌تان فراتر رفته‌اید. | منتظر بمانید تا سهمیه بازنشانی شود یا درخواست افزایش سهمیه کنید. |
too_many_requests |
۴۲۹ درخواست‌های بسیار زیاد | در مدت زمان کوتاهی درخواست‌های زیادی ارسال کرده‌اید. | صبر کنید و با عقب‌گرد نمایی دوباره امتحان کنید. |
cancelled |
۴۹۹ Client Closed Request | کارخواه درخواست را پیش‌از تکمیل لغو کرد. | لازم نیست اقدامی انجام دهید. این معمولاً به این معنی است که اتصال کارخواه قطع شده است. |
api_error |
۵۰۰ خطای سرور داخلی | خطای غیرمنتظره‌ای در سرور رخ داد. | درخواست را دوباره امتحان کنید. اگر مشکل برطرف نشد، با پشتیبانی تماس بگیرید. |
unimplemented |
خطای ۵۰۱ - پیاده‌سازی نشده است | عملیات یا ویژگی پیاده‌سازی یا پشتیبانی نمی‌شود. | قابلیت‌های میانای برنامه‌سازی کاربردی را بررسی کنید یا به ویژگی پشتیبانی‌شده‌ای بروید. |
service_unavailable |
خطای ۵۰۳ - سرویس دردسترس نیست | سرویس موقتاً دچار بار اضافی شده یا قطع است. | صبر کنید و با عقب‌گرد نمایی دوباره امتحان کنید. |
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 |
پاسخ فاقد امضای تفکر الزامی است. |
قالب پاسخ خطا
همه خطاهای Interactions API یک شیء 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 |
رشته | توضیحی قابل‌خواندن برای انسان درباره مشکل پیش‌آمده. |
نحوه ارائه خطاها
این API خطاها را بسته به اینکه درخواست استاندارد HTTP یا درخواست جاری‌سازی (SSE) داشته باشید به‌صورت متفاوتی ارائه می‌دهد.
درخواست‌های استاندارد اچ‌تی‌تی‌پی
برای درخواست‌های استاندارد (غیرجاری‌سازی)، میانای برنامه‌سازی کاربردی رمز وضعیت پاسخ‌های 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)، میانای برنامه‌سازی کاربردی رویدادهای خطا را ازطریق جاری‌سازی «رویدادهای ارسال‌شده از سرور» (SSE) با event_type تنظیم‌شده روی "error" ارسال می‌کند. فیلد error حاوی ساختار code و message یکسان است:
{
"event_type": "error",
"error": {
"code": "not_found",
"message": "Failed to get completed interaction: Result not found."
}
}
برای مشاهده طرح‌واره کامل رویداد SSE، به مرجع Interactions API مراجعه کنید.
قدم بعدی چیست
- عیب‌یابی API: حل مشکلات رایج و سناریوهای خطا.
- حدود نرخ: درباره حدود درخواست و مدیریت سهمیه بیشتر بدانید.