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

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

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

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

الرمز رموز حالة HTTP الوصف الإجراء المقترَح
invalid_request 400 Bad Request حمولة الطلب غير صالحة أو تحتوي على مَعلمات غير صالحة. راجِع بنية الطلب ومَعلماته مقارنةً بمرجع واجهة برمجة التطبيقات API.
failed_precondition 400 Bad Request يتعذّر معالجة الطلب لأنّه لم يتم استيفاء شرط أساسي (على سبيل المثال، تم إيقاف الفوترة). تحقَّق من حالة الفوترة في المشروع أو من الشروط الأساسية للحساب.
out_of_range 416 Requested Range Not Satisfiable مَعلمة الطلب خارج النطاق الصالح. راجِع قيم المَعلمات وحدودها.
parameter_unknown 400 Bad Request يحتوي الطلب على مَعلمة غير معروفة. أزِل المَعلمة غير المعروفة وأعِد المحاولة.
authentication ‫401 غير مصرّح به مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح أو منتهي الصلاحية. تحقَّق من مفتاح واجهة برمجة التطبيقات.
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.

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