رموز الأخطاء وتشخيصها

حدد ما الذي فشل

1. سجل حالة HTTP الفعلية وطريقة الطلب ومساره. تصف حالة HTTP ورمز خطأ التطبيق طبقتين مختلفتين؛ ولا تستبدل أحدهما بالآخر.
2. اقرأ حقول الخطأ بحسب البروتوكول الذي استدعيته. لا تشترك الاستجابات الأصلية وOpenAI وClaude وGemini كلها في البنية نفسها.
3. لطلبات البث، افحص أيضا أحداث الخطأ وحالة الاكتمال. وللمهام غير المتزامنة، افحص status المهمة. لا تضمن HTTP 200 نجاح التوليد.
4. استخدم الجدول أدناه لإصلاح الطلب أو تحديد ما إذا كنت ستعيد المحاولة. message نص توضيحي، وليس تعدادا ثابتا؛ ولا تبن تفرعات منطقية على صياغته.

تعداد رموز أخطاء المنصة

هذا هو التعداد الكامل لرموز أخطاء تطبيق المنصة. الأسماء تسميات مرجعية؛ وقيم code في الاستجابة أرقام. «HTTP الشائع» دليل للتشخيص، وليس تطابقا ثابتا لكل نقطة نهاية. استخدم حالة HTTP الفعلية وجسم الاستجابة. قد لا ينتمي code الممرر من المزود إلى هذا التعداد.

لا يمكن التمييز بصورة موثوقة بين حدود المعدل وحدود التزامن من HTTP 429 وحده. ميز بينهما فقط عند توفر رمز خطأ رقمي صريح. تحقق من معرفات النماذج في قائمة النماذج؛ ولا تعد كتابة قيم model بنفسك.

اقرأ الأخطاء بحسب البروتوكول

تعرض الأمثلة أدناه بنيات شائعة تولدها المنصة، وليس تنسيقا واحدا مضمونا لكل إخفاق. قد تعيد طبقات معالجة مختلفة إخفاقات المصادقة، وقد تحتفظ استجابات المزود الممررة ببنياتها ورموزها النصية أو أنواعها. حدد بنية الاستجابة الفعلية قبل تحليلها. وإذا كانت غير معروفة، فاحفظ الحقول الأصلية وحالة HTTP بدلا من فرض تحويل.

واجهات API الأصلية للمنصة

اقرأ عادة error.code وerror.message. قد يغيب requestId.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

قد تستخدم بعض الأخطاء code وmessage على المستوى الأعلى. ينبغي للعملاء استيعاب هذا الاختلاف وألا يعدوا غياب كائن error دليلا على النجاح. قد تخلو استجابات التحقق من المعاملات أيضا من رمز خطأ رقمي. تعامل مع الرمز المفقود بوصفه مجهولا بدلا من اختلاقه.

واجهات API المتوافقة مع OpenAI

تستخدم الأخطاء الشائعة التي تولدها المنصة code وmessage وtype على المستوى الأعلى؛ ولا تكون بالضرورة داخل error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type فئة بروتوكول؛ وcode هو رمز الخطأ الرقمي للمنصة في هذه البنية. لا يحدد api_error وحده ملاءمة إعادة المحاولة. قد تتضمن أخطاء البث والاستجابات الممررة من المزود كائن error متداخلا؛ عالج استجابة البروتوكول الفعلية. راجع واجهة Chat Completions وواجهة Responses.

واجهات API المتوافقة مع Claude

في البنية الشائعة، تكون قيمة type على المستوى الأعلى هي error، والفئة المحددة هي error.type، والوصف هو error.message. لا تتضمن هذه البنية code رقميا للمنصة. لا تختلقه.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

تولد المنصة محليا أنواع أخطاء Claude التالية. هذا ليس تعدادا شاملا لأنواع أخطاء المزود.

راجع واجهة Claude Messages.

أخطاء بأسلوب Gemini

عندما تتلقى استجابة بأسلوب Gemini، اقرأ error.code وerror.message وerror.status. هنا، status فئة نصية، وليست حالة HTTP أو حالة مهمة غير متزامنة.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

تستخدم الأخطاء التي تولدها المنصة بهذه البنية قيم code الرقمية للمنصة. مطابقة status النصية المحلية أدناه؛ وليست تعدادا لجميع حالات المزود.

تكون الأولوية لـ503 وتستخدم UNAVAILABLE، وليس INTERNAL. قد تستخدم استجابات المزود دلالات مختلفة لـcode وstatus. لا تطبق جدول رموز أخطاء المنصة على كل رمز Gemini رقمي.

أعد المحاولة بأمان

احترم ترويسة Retry-After الصحيحة عند وجودها. لا تفترض وجودها في كل خطأ. قد تؤدي إعادة طلب توليد غير ثابت الأثر تلقائيا إلى تنفيذه مجددا واحتساب رسوم إضافية. لا تعد هذه الصفحة بدعم عام لمفاتيح منع التكرار؛ وإضافة Idempotency-Key بنفسك لا تضمن إزالة التكرار.

إذا كان لديك jobId بالفعل، فاستعلم عن تلك المهمة قبل إنشاء أخرى. وإذا لم يكن لديك jobId وكانت النتيجة غير مؤكدة، فاحفظ معرف الطلب والطابع الزمني للتحقيق.

البث والمهام غير المتزامنة

طلبات SSE

بعد بدء SSE، قد تبقى حالة HTTP هي 200 بينما يبلغ إخفاق لاحق عبر حدث خطأ أو حمولة داخل البث. حلل الأحداث والبيانات للبروتوكول المختار وتحقق من الاكتمال الطبيعي. عند خطأ أو انقطاع غير متوقع، لا تعتبر النص أو الصور الجزئية نتيجة ناجحة مكتملة. تختلف أسماء الأحداث والحمولات بين نقاط النهاية. لا تفحص حقل error ثابتا واحدا فقط، ولا تستخدم «تلقي أي نص» شرطا للنجاح.

المهام غير المتزامنة

تعني استجابة الإنشاء التي تتضمن data.jobId قبول الطلب، وليس اكتمال التوليد. وتعني استجابة HTTP الناجحة عند الاستعلام عن مهمة نجاح الاستعلام. يجب مع ذلك فحص data.status للمهمة:

• PENDING وCONNECT وPROCESSING: واصل الاستطلاع كما توضح وثائق المهام.
• COMPLETED: اقرأ outputResult.
• FAILED وCANCELLED: أوقف الاستطلاع واحفظ معرف المهمة ومعلومات الاستجابة المنقحة للتحقيق.

قد تظهر تفاصيل الإخفاق في data.outputResult.error. هذا الحقل اختياري وغير مضمون لكل مهمة فاشلة. استخدم Jobs فقط عندما تعيد استجابة الإنشاء jobId صراحة. لا تطبق استطلاع المهام على نقاط النهاية التي تعيد النتائج مباشرة عبر JSON أو SSE.

التشخيص للمستخدمين ومساعدي الذكاء الاصطناعي

قدم المعلومات المنقحة التالية إلى الدعم أو مساعد ذكاء اصطناعي. استخدم unknown للحقول الغائبة؛ واستخدم unknown لحالة HTTP إذا لم تتلق استجابة HTTP. احفظ مسارات الحقول وأنواع القيم الأصلية، مثلا error.code: 10000 (number) أو error.code: "invalid_api_key" (string). لا تحول code النصي تلقائيا إلى رمز رقمي للمنصة ولا تختلق الحقول المفقودة من message أو حالة HTTP أو أسماء النماذج.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

اقرأ requestId من جسم الاستجابة أو ترويسة الاستجابة X-Request-ID عند توفرها. أبق jobId سلسلة نصية لتجنب فقدان الدقة مع الأعداد الطويلة. قدم الحد الأدنى من معاملات الطلب المنقحة فقط. أزل مفاتيح API والرموز وملفات الارتباط وترويسات المصادقة الكاملة والمعلومات الشخصية والتعليمات الخاصة ومحتويات ملفات الإدخال. أزل معاملات استعلام URL وعناوين المدخلات أو المخرجات التي تتضمن توقيعات أو بيانات اعتماد وصول. لا تلصق سجلات الطلبات كاملة دون مراجعتها.

ينبغي لمساعدي الذكاء الاصطناعي التمييز بين الحقول الملاحظة والأسباب المحتملة وتحديد المعلومات المفقودة. لا يجوز اعتبار نقص الأدلة إثباتا لنجاح طلب أو عدم تنفيذه أو عدم ترتب رسوم عليه.