تكون معالجة أخطاء CometAPI أسهل عندما تفصل بين مشكلات بنية الطلب، ومشكلات المصادقة، وأخطاء المسار، وإخفاقات المنصة القابلة لإعادة المحاولة. استخدم مزيجًا من حالة HTTP وerror.code وerror.message لتحديد ما إذا كان يجب إصلاح الطلب أو إعادة المحاولة.
فرز سريع
غلاف الخطأ
تستخدم كثير من حالات فشل CometAPI جسم خطأ مثل هذا:
تترك بعض الاستجابات code فارغًا. عندما تكون الحالة 500، تعامل مع error.code وerror.message بوصفهما الإشارة الحاسمة.
400 Bad Request
يعني 400 عادةً أن جسم الطلب فشل في التحقق من الصحة قبل أن تتم معالجة الطلب بشكل طبيعي.
الأسباب الشائعة:
- حقول مطلوبة مفقودة مثل
model
- بنية JSON غير صالحة
- إرسال حقل بنوع غير صحيح
- إعادة استخدام معلمات خاصة بالمزوّد لا يقبلها endpoint المحدد
ابدأ من طلب أدنى سليم معروف، ثم أعد إضافة الحقول الاختيارية واحدًا تلو الآخر. قارن الحمولة مع مخطط endpoint في مرجع API.
استخدم طلبًا بسيطًا مثل هذا:
استبدل your-model-id بأي model ID حالي من صفحة نماذج CometAPI.
لا تفترض أن كل طلب chat غير صحيح يعيد 400. فقد تظهر أيضًا الحقول المطلوبة المفقودة في chat مثل messages على شكل 500 مع error.code: invalid_request.
500 Internal Server Error
تشير معظم استجابات 500 إلى فشل في المنصة أو المزوّد. بالنسبة إلى Chat Completions، قد تظهر بعض الطلبات غير الصحيحة أيضًا على شكل 500 مع استمرار تضمين error.code: invalid_request.
أحد الأمثلة هو طلب يحذف messages:
إذا كانت استجابة 500 تتضمن error.code: invalid_request، فتعامل معها على أنها مشكلة في الطلب:
- أصلح جسم الطلب.
- قارن الحمولة مع مخطط endpoint.
- أعد المحاولة فقط بعد تصحيح الحمولة.
إذا كانت استجابة 500 لا تشير إلى طلب غير صحيح، فاحتفظ بـ request id واستخدم backoff.
401 Invalid Token
عادةً ما يبدو فشل token بهذا الشكل:
ما الذي يجب التحقق منه:
- يجب أن يكون الـ header بالشكل المطابق تمامًا
Authorization: Bearer $COMETAPI_KEY.
- تأكد من أن تطبيقك لا يحمّل مفتاحًا قديمًا من
.env أو سجل shell أو مخزن secrets منشور.
- إذا فشل مفتاح واحد ونجح مفتاح آخر مع الطلب نفسه، فاعتبر هذه مشكلة token وليست مشكلة endpoint.
403 Forbidden
غالبًا ما تكون 403 إحدى هذه الحالات:
- تم حظر الطلب بواسطة قاعدة على مستوى المنصة مثل تصفية WAF
- token أو route غير مصرح لهما باستخدام model المطلوب أو شكل الطلب المطلوب
- model المختار يرفض أحد المعلمات المتقدمة التي مررتها
ما الذي يجب فعله أولًا:
- أعد المحاولة باستخدام طلب نصي بسيط جدًا مع model معروف بأنه يعمل.
- أزل الحقول المتقدمة والمعلمات الخاصة بـ provider، ثم أعد إضافتها تدريجيًا.
- إذا كانت الاستجابة تتضمن request id، فاحتفظ به قبل التواصل مع الدعم.
إذا كانت الرسالة تذكر مصطلحات داخلية مثل group أو channel، فتعامل معها على أنها تفاصيل توجيه، وليس كأول شيء يجب تشخيصه من جهة العميل. يظل الحل العملي هو التحقق أولًا من token وmodel وشكل الطلب.
عنوان URL أساسي خاطئ أو مسار خاطئ
في Comet، قد يظهر خطأ في المسار على شكل:
- إعادة توجيه
- استجابة HTML غير JSON إذا كان العميل لديك يتبع عمليات إعادة التوجيه
- خطأ parsing داخل SDK الخاص بك
- طلب لا يصل أبدًا إلى طبقة API بشكل سليم
استخدم عنوان URL الأساسي هذا كما هو تمامًا:
عمليات تحقق موصى بها:
- تأكد من أن عنوان URL الأساسي يتضمن
/v1.
- تأكد من أن مسار endpoint يطابق التوثيق تمامًا.
- عطّل التتبع التلقائي لعمليات إعادة التوجيه أثناء تصحيح مشكلات المسار.
413 Request Entity Too Large
إذا رأيت 413، فاعتبرها أولًا مشكلة حجم الطلب. من الأسباب الشائعة:
- حمولات base64 كبيرة
- صور أو ملفات صوتية كبيرة جدًا مضمنة inline
- أجسام multipart أو JSON كبيرة جدًا
ما الذي يجب فعله:
- قلّل حجم المحتوى المرفق أو اضغطه.
- قسّم المهام الكبيرة إلى طلبات أصغر.
- لا تفترض أن طول النص العادي هو السبب الوحيد.
429 Too Many Requests
تعامل مع 429 على أنها قابلة لإعادة المحاولة:
- استخدم exponential backoff مع jitter.
- قلّل التزامن الاندفاعي.
- أبقِ تسجيل الطلبات مفعّلًا حتى تتمكن من معرفة أي route وأي model يصل إلى حد التشبع أولًا.
للاطلاع على نمط قابل لإعادة الاستخدام لإعادة المحاولة، راجع مثال backoff في Chat Completions.
503, 504, and 524
هذه الحالات هي إخفاقات من جهة الخادم أو من فئة المهلة الزمنية.
إرشادات عملية:
503: route أو خدمة provider غير متاحة مؤقتًا504 و 524: إخفاقات من فئة المهلة الزمنية بين المنصة أو edge أو خدمة provider
ما الذي يجب فعله:
- أعد المحاولة باستخدام backoff.
- احتفظ بـ
request id وendpoint وmodel والطابع الزمني.
- إذا تكرر الإخفاق نفسه عبر عدة محاولات إعادة، فتواصل مع الدعم مع تزويدهم بهذا السياق.
قبل التواصل مع الدعم
التقط هذه التفاصيل أولاً:
- طريقة HTTP
- مسار نقطة النهاية
- Model ID
- JSON لهيئة الطلب بعد تنقيح البيانات الحساسة (وهذا هو العنصر الأكثر فائدة في معظم استدعاءات API)
- معاملات الاستعلام إذا كان الطلب الذي فشل يستخدمها
- نص هيئة الاستجابة بالكامل إذا كان عميلك قد التقطه
- حالة HTTP الكاملة
- قيمة
error.message الدقيقة
- أي
request id
- طابع زمني تقريبي
- ما إذا كان الطلب نفسه يعمل مع model آخر أو token آخر
إذا كان المسار الذي فشل يقبل رفع الملفات (تحرير الصور، رفع الصوت، إنشاء الفيديو، إلخ) بدلاً من هيئة JSON عادية، فأرسل الحمولة المكافئة التي تم إرسالها:
- أسماء الحقول والقيم النصية التي أرسلتها مع الملف
- اسم الملف ونوعه وحجم الملف التقريبي
- ما إذا كان الملف قد رُفع مباشرةً، أو تمت الإشارة إليه عبر URL، أو تم تضمينه بصيغة base64
الطريقة الأكثر فعالية لإعادة إنتاج bug هي حمولة الطلب الدقيقة بعد تنقيح البيانات الحساسة. بالنسبة لمعظم استدعاءات API، فهذا يعني JSON الخام لهيئة الطلب. أما بالنسبة للمسارات التي تعتمد على رفع الملفات، فهذا يعني قائمة الحقول بالإضافة إلى بيانات الملف الوصفية.
