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

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

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

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

الرمز حالة HTTP الوصف الإجراء المقترَح
invalid_request ‫400 طلب غير صالح حمولة الطلب مكتوبة بشكل غير صحيح أو تحتوي على مَعلمات غير صالحة. تحقَّق من بنية الطلب ومَعلماته مقارنةً بمرجع واجهة برمجة التطبيقات.
failed_precondition ‫400 طلب غير صالح يتعذّر معالجة الطلب لأنّ أحد الشروط الأساسية غير مستوفى (على سبيل المثال، إيقاف الفوترة). تحقَّق من حالة فوترة المشروع أو المتطلبات الأساسية للحساب.
out_of_range 416 Requested Range Not Satisfiable مَعلمة الطلب خارج النطاق الصالح. تحقَّق من قيم المَعلمات وحدودها.
parameter_unknown ‫400 طلب غير صالح يحتوي الطلب على مَعلمة غير معروفة. يُرجى إزالة المَعلمة التي لم يتم التعرّف عليها وإعادة المحاولة.
authentication ‫401 غير مصرّح به مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح أو انتهت صلاحيته. تأكَّد من مفتاح واجهة برمجة التطبيقات.
payment_required 402 Payment Required تم استنفاد رصيد الدفع المُسبَق. أضِف رصيدًا إلى حساب الفوترة أو فعِّل ميزة تعبئة الرصيد تلقائيًا. لا تعِد المحاولة: لن ينجح الطلب إلى أن تتم إضافة الرصيد.
permission_denied ‫403 Forbidden لا يملك مفتاح واجهة برمجة التطبيقات الإذن بالوصول إلى هذا المرجع. تحقَّق من أذونات مفتاح واجهة برمجة التطبيقات وإذن الوصول إلى المشروع.
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 Client Closed Request ألغى العميل الطلب قبل اكتماله. ليس عليك اتخاذ أي إجراء. يعني هذا عادةً أنّه تم قطع اتصال البرنامج.
api_error ‫500 Internal Server Error حدث خطأ غير متوقَّع في الخادم. أعِد محاولة إرسال الطلب. في حال استمرار المشكلة، يُرجى التواصل مع فريق الدعم.
unimplemented 501 Not Implemented لم يتم تنفيذ العملية أو الميزة أو لا تتوافق مع الجهاز. تحقَّق من إمكانات واجهة برمجة التطبيقات أو بدِّل إلى ميزة متوافقة.
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)، ترسل واجهة برمجة التطبيقات أحداث الخطأ عبر بث 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.

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