أخطاء واجهة برمجة التطبيقات

تقدّم هذه الصفحة مرجعًا لجميع رموز الخطأ في Interactions API، وتوضّح تنسيق الاستجابة للأخطاء، وتشرح كيفية عرض واجهة برمجة التطبيقات للأخطاء في أنواع الطلبات المختلفة.

رموز الخطأ العادية في واجهة برمجة التطبيقات

تتوافق رموز الأخطاء العامة هذه على مستوى الطلب مع رموز حالة HTTP العادية. استخدِم حقل code في منطق التطبيق لمعالجة الأخطاء آليًا.

الرمز حالة HTTP الوصف الإجراء المقترَح
invalid_request ‫400 طلب غير صالح حمولة الطلب مكتوبة بشكلٍ غير صحيح أو تحتوي على معلَمات غير صالحة. تحقَّق من بنية الطلب ومَعلماته مقارنةً بمرجع واجهة برمجة التطبيقات.
failed_precondition ‫400 طلب غير صالح يتعذّر على الخادم معالجة الطلب لأنّه لم يتم استيفاء أحد الشروط الأساسية (على سبيل المثال، تم إيقاف الفوترة). يُرجى التحقّق من حالة الفوترة في المشروع أو المتطلبات الأساسية للحساب.
out_of_range ‫416 النطاق المطلوب غير قابل للتلبية مَعلمة الطلب خارج النطاق الصالح. يُرجى التحقّق من قيم المَعلمات وحدودها.
parameter_unknown ‫400 طلب غير صالح يحتوي الطلب على معلَمة غير معروفة. يُرجى إزالة المَعلمة غير المعروفة وإعادة المحاولة.
authentication ‫401 غير مصرّح به مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح أو منتهي الصلاحية. تحقَّق من مفتاح واجهة برمجة التطبيقات.
payment_required ‫402 مطلوب الدفع نفد رصيد الدفع المُسبَق. أضِف رصيدًا إلى حساب الفوترة أو فعِّل ميزة إعادة التعبئة التلقائية. لا تُعِد المحاولة: لن ينجح الطلب إلا بعد إضافة أرصدة.
permission_denied ‫403 محظور لا يملك مفتاح واجهة برمجة التطبيقات إذنًا للوصول إلى هذا المورد، أو أنّ إمكانية وصول مشروعك إلى واجهة برمجة التطبيقات مقيّدة. يُرجى التحقّق من أذونات مفتاح واجهة برمجة التطبيقات وأهلية فئة المشروع وحالة الفوترة. يُرجى الاطّلاع على تحديد المشاكل وحلّها في ما يتعلّق بالمشاريع المحظورة أو غير المتاحة.
not_found ‫404 لم يتم العثور على الصفحة لم يتم العثور على المصدر المطلوب. يُرجى التحقّق من مسار المورد والمَعلمات.
model_not_found ‫404 لم يتم العثور على الصفحة لم يتم العثور على النموذج المحدّد. يُرجى التحقّق من اسم النموذج أو استخدام نموذج آخر.
already_exists ‫409 Conflict الكيان الذي حاولت إنشاؤه موجود مسبقًا. يُرجى التحقّق مما إذا كان المورد متوفّرًا قبل إعادة إنشائه.
aborted ‫409 Conflict تم إلغاء العملية بسبب تعارض أو تعذُّر التحقّق من التزامن. يُرجى إعادة محاولة إرسال الطلب على مستوى أعلى للتطبيق.
rate_limit_exceeded ‫429 Too Many Requests لقد تجاوزت الحد الأقصى المسموح به للطلبات أو الرموز المميّزة في الدقيقة أو الثانية. يُرجى الانتظار وإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
quota_exceeded ‫429 Too Many Requests لقد تجاوزت حصتك اليومية. يُرجى الانتظار إلى أن تتم إعادة ضبط الحصة أو طلب زيادة الحصة.
too_many_requests ‫429 Too Many Requests لقد أرسلت عددًا كبيرًا من الطلبات في فترة قصيرة. يُرجى الانتظار وإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
cancelled ‫499: أغلق العميل الطلب ألغى العميل الطلب قبل اكتماله. ليس عليك اتّخاذ أي إجراء. يعني هذا عادةً أنّ العميل قد قطع الاتصال.
api_error ‫500: خطأ في الخادم الداخلي حدث خطأ غير متوقَّع في الخادم. أعِد محاولة إرسال الطلب. في حال استمرار المشكلة، يُرجى التواصل مع فريق الدعم.
unimplemented ‫501 غير مُنفَّذ لم يتم تنفيذ العملية أو الميزة أو لم يتم توفيرها. يُرجى التحقّق من إمكانات واجهة برمجة التطبيقات أو التبديل إلى ميزة متوافقة.
service_unavailable ‫503 الخدمة غير متاحة الخدمة معطّلة أو تواجه حملاً زائدًا مؤقتًا. يُرجى الانتظار وإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
deadline_exceeded ‫504 انتهت مهلة البوابة لم يكتمل الطلب خلال الموعد النهائي. يُرجى إزالة إعداد الموعد النهائي للعميل أو زيادته لاستخدام الإعداد التلقائي للخادم.

رموز حظر الإنشاء

تشير رموز الخطأ هذه إلى أنّ ردّ النموذج تم حظره بسبب قيود السياسة أو الأمان أو المحتوى. عند تلقّي أحد هذه الرموز، عدِّل الإدخال وأعِد المحاولة.

الرمز الوصف
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 سلسلة وصف يمكن لشخص عادي قراءته لما حدث من خطأ

كيفية إرسال الأخطاء

تعرض واجهة برمجة التطبيقات الأخطاء بشكل مختلف استنادًا إلى ما إذا كنت تُجري طلب HTTP عاديًا أو طلب بث (SSE).

طلبات HTTP العادية

بالنسبة إلى الطلبات العادية (غير المتعلّقة بالبث)، تضبط واجهة برمجة التطبيقات رمز حالة استجابة 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.

الخطوات التالية