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

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

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

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

الرمز حالة HTTP الوصف الإجراء المقترَح
invalid_request ‫400 طلب غير صالح الطلب مكتوب بشكل غير صحيح أو يحتوي على مَعلمات غير صالحة. راجِع بيانات الإدخال مقارنةً بمرجع واجهة برمجة التطبيقات.
parameter_unknown ‫400 طلب غير صالح يحتوي الطلب على مَعلمة غير معروفة. يُرجى إزالة المَعلمة التي لم يتم التعرّف عليها وإعادة المحاولة.
authentication ‫401 غير مصرّح به مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح. تأكَّد من مفتاح واجهة برمجة التطبيقات.
permission_denied ‫403 Forbidden لا يملك مفتاح واجهة برمجة التطبيقات الإذن بالوصول إلى هذا المرجع. تحقَّق من أذونات مفتاح واجهة برمجة التطبيقات وإذن الوصول إلى المشروع.
not_found ‫404 لم يتم العثور على الصفحة لم يتم العثور على المورد المطلوب. تحقَّق من مسار المورد ومَعلماته.
model_not_found ‫404 لم يتم العثور على الصفحة لم يتم العثور على النموذج المحدّد. تحقَّق من اسم النموذج أو استخدِم نموذجًا مختلفًا.
rate_limit_exceeded 429 Too Many Requests تجاوزت الحد الأقصى للطلبات أو الرموز المميزة في الدقيقة أو الثانية. يُرجى الانتظار وإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
quota_exceeded 429 Too Many Requests لقد تجاوزت الحصة اليومية المتاحة لك. يُرجى الانتظار إلى أن تتم إعادة ضبط الحصة أو طلب زيادة الحصة.
cancelled ‫499 Client Closed Request ألغى العميل الطلب قبل اكتماله. ليس عليك اتخاذ أي إجراء. يعني هذا عادةً أنّه تم قطع اتصال البرنامج.
api_error ‫500 Internal Server Error حدث خطأ غير متوقَّع في الخادم. أعِد محاولة إرسال الطلب. في حال استمرار المشكلة، يُرجى التواصل مع فريق الدعم.
service_unavailable ‫503 الخدمة غير متاحة الخدمة معطّلة مؤقتًا أو هناك زيادة مؤقتة في التحميل عليها. يُرجى الانتظار وإعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.

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

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

الرمز الوصف
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)، ترسل واجهة برمجة التطبيقات أحداث الخطأ عبر بث Server-Sent Events (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.

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