الانتقال إلى المحتوى الرئيسي
تكون معالجة أخطاء CometAPI أسهل عندما تفصل بين مشكلات الطلب ومشكلات المصادقة ومشكلات المنصة القابلة لإعادة المحاولة. تُعد هذه الصفحة الدليل المرجعي الرسمي لأخطاء CometAPI، وتركّز على ما يمكنك التحقق منه من جهة العميل أولًا.
يستند هذا الدليل إلى عمليات تحقق مباشرة من واجهة CometAPI API الحالية. لقد تحقّقنا مباشرة من أخطاء 400 و401 وأعطال المسار/base URL. ولم نُعِد إنتاج أخطاء 413 أو 429 أو 500 أو 503 أو 504 أو 524 ضمن اختبارات محدودة، لذلك فإن الإرشادات الخاصة بهذه الحالات متحفّظة عمدًا.

​
الفرز السريع

Statusما الذي يعنيه عادةًإعادة المحاولة؟الإجراء الأول
400فشل التحقق من صحة الطلب قبل أن يتم توجيهه بنجاح.لاتحقّق من model وmessages وبنية JSON وأنواع الحقول.
401مفتاح API مفقود أو غير صالح أو ذو تنسيق غير صحيح.لاتحقّق من Authorization: Bearer <COMETAPI_KEY>.
403تم حظر الوصول أو لم يكن الطلب الحالي مسموحًا به.غالبًا لاأعد المحاولة باستخدام طلب سليم معروف، وأزل الحقول الخاصة بالنموذج أولًا.
خطأ في المسارعنوان base URL غير صحيح أو مسار endpoint غير صحيح. في Comet قد يظهر هذا على شكل إعادة توجيه 301 أو HTML، وليس 404 نظيفًا بصيغة JSON.لااستخدم https://api.cometapi.com/v1 كما هو تمامًا، وعطّل اتباع إعادة التوجيه تلقائيًا أثناء تصحيح الأخطاء.
429تحديد معدل الطلبات أو تشبّع مؤقت.نعماستخدم exponential backoff مع jitter.
500, 503, 504, 524عطل في المنصة أو عطل من فئة timeout.نعمأعد المحاولة مع backoff واحتفِظ بمعرّف الطلب.

​
غلاف الخطأ

يبدو غلاف الخطأ الحالي بصيغة JSON الذي تعيده CometAPI كما يلي: 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
تتضمن كثير من رسائل الأخطاء الفعلية أيضًا request id داخل error.message. احفظ هذه القيمة عندما تحتاج إلى الدعم.

​
400 Bad Request

ما لاحظناه من واجهة API المباشرة عندما تم حذف model: 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
عمليًا، يعني 400 عادةً أن جسم الطلب فشل في التحقق من الصحة قبل أن تتمكن المنصة من توجيهه إلى موفّر النموذج. الأسباب الشائعة:
  • غياب الحقول المطلوبة مثل model أو messages
  • بنية JSON غير صالحة
  • إرسال حقل بنوع غير صحيح
  • إعادة استخدام معاملات خاصة بموفّر لا تقبلها نقطة endpoint المحددة
ما الذي يجب فعله:
  1. ابدأ بطلب أساسي سليم ومعروف.
  2. أعد إضافة الحقول الاختيارية واحدًا تلو الآخر.
  3. قارن جسم الطلب بمخطط endpoint في مرجع API.
مثال أساسي سليم ومعروف: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
استبدل your-model-id بأي معرّف نموذج حالي من صفحة نماذج CometAPI.

​
401 Invalid Token

ما لاحظناه من واجهة API المباشرة عند استخدام مفتاح غير صالح: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
ما الذي يجب التحقق منه:
  1. يجب أن يكون الترويس بالضبط Authorization: Bearer <COMETAPI_KEY>.
  2. تأكد من أن تطبيقك لا يحمّل مفتاحًا قديمًا من .env أو سجل shell أو مخزن الأسرار في بيئة النشر.
  3. إذا فشل مفتاح واحد ونجح مفتاح آخر مع الطلب نفسه، فاعتبر ذلك مشكلة في token وليس مشكلة في endpoint.

​
403 Forbidden

لم نتمكن من إعادة إنتاج حالة 403 مستقرة في اختبارات محدودة، لذا تجنّب اعتبار قالب رسالة قديم واحد على أنه يروي القصة كاملة. في وثائق Comet الحالية، تتم مناقشة 403 غالبًا باعتباره إحدى هذه الحالات:
  • يتم حظر الطلب بواسطة قاعدة على مستوى المنصة مثل تصفية WAF
  • لا يُسمح للـ token أو المسار باستخدام model المطلوب أو شكل الطلب المطلوب
  • يرفض model المختار أحد المعلمات المتقدمة التي مررتها
ما الذي ينبغي فعله أولًا:
  1. أعد المحاولة باستخدام طلب نصي بسيط جدًا على model معروف بأنه يعمل بشكل صحيح.
  2. أزل الحقول المتقدمة والمعلمات الخاصة بمزوّد الخدمة، ثم أعد إضافتها تدريجيًا.
  3. إذا كانت الاستجابة تتضمن request id، فاحتفظ به قبل التواصل مع الدعم.
إذا كانت الرسالة تشير إلى مصطلحات داخلية مثل group أو channel، فاعتبرها تفاصيل توجيه، وليس أول ما ينبغي تشخيصه من جهة العميل. يظل الحل العملي هو التحقق أولًا من token وmodel وشكل الطلب.

​
Base URL خاطئ أو Path خاطئ

هذه هي المنطقة التي كانت فيها الصفحة القديمة الأقل دقة. في عمليات التحقق المباشرة مقابل نقاط نهاية Comet الحالية:
  • أدى الإرسال إلى https://api.cometapi.com/chat/completions إلى إرجاع إعادة توجيه 301 نحو https://www.cometapi.com/chat/completions
  • أدى الإرسال إلى مسار API وهمي مثل https://api.cometapi.com/v1/not-a-real-endpoint أيضًا إلى إرجاع إعادة توجيه 301 نحو https://www.cometapi.com/v1/not-a-real-endpoint
وهذا يعني أن الخطأ في path قد يظهر على شكل:
  • إعادة توجيه
  • استجابة HTML غير بتنسيق JSON إذا كان العميل لديك يتبع عمليات إعادة التوجيه
  • خطأ تحليل parsing داخل SDK لديك
  • طلب لا يصل أبدًا إلى طبقة API بشكل سليم
استخدم Base URL هذا كما هو تمامًا: 
https://api.cometapi.com/v1
الفحوصات الموصى بها:
  1. تأكد من أن Base URL يتضمن /v1.
  2. تأكد من أن path الخاص بنقطة النهاية يطابق الوثائق تمامًا.
  3. عطّل المتابعة التلقائية لإعادة التوجيه أثناء تصحيح مشكلات path.

​
413 Request Entity Too Large

لم نتمكن من إعادة إنتاج 413 في اختبار محدود، حتى مع جسم طلب JSON كبير بحجم 8 MiB، لذا كان التفسير القديم بأن prompt طويل جدًا تفسيرًا ضيقًا أكثر من اللازم. إذا ظهرت لك 413، فتعامل معها أولًا على أنها مشكلة حجم الطلب. ومن أكثر الأسباب الشائعة:
  • حمولات base64 كبيرة
  • صور أو ملفات صوتية كبيرة جدًا مضمّنة inline
  • أجسام multipart أو JSON كبيرة جدًا
ما الذي ينبغي فعله:
  1. قلّل حجم المحتوى المرفق أو اضغطه.
  2. قسّم المهام الكبيرة إلى طلبات أصغر.
  3. لا تفترض أن طول النص العادي هو السبب الوحيد.

​
429 Too Many Requests

لم نتمكن من إعادة إنتاج 429 أثناء اختبار محدود للتزامن شمل 24 طلب GET /v1/models متوازيًا، لذا فمن الواضح أن الحد الدقيق يعتمد على المسار وmodel والحالة الحالية للمنصة. تعامل مع 429 على أنها قابلة لإعادة المحاولة:
  1. استخدم exponential backoff مع jitter.
  2. قلّل التزامن في الاندفاعات.
  3. أبقِ تسجيل الطلبات مفعّلًا حتى تتمكن من معرفة أي مسار وأي model يصلان إلى التشبع أولًا.
للاطلاع على نمط إعادة محاولة قابل لإعادة الاستخدام، راجع مثال backoff في Chat Completions.

​
500, 503, 504, And 524

لم نتمكن من إعادة إنتاج رموز الحالة هذه في اختبارات محدودة. ينبغي توثيقها على أنها إخفاقات من جهة الخادم أو من فئة المهلات الزمنية، وليس باعتبارها أخطاء من المستخدم. إرشادات عملية:
  • 500: فشل داخلي في المنصة أو من جهة مزوّد الخدمة
  • 503: المسار أو خدمة المزوّد غير متاحة مؤقتًا
  • 504 و 524: إخفاقات من فئة المهلات الزمنية بين المنصة أو الحافة أو خدمة المزوّد
ما الذي ينبغي فعله:
  1. أعد المحاولة مع backoff.
  2. احتفظ بـ request id ونقطة النهاية وmodel والطابع الزمني.
  3. إذا تكرر الإخفاق نفسه عبر عدة محاولات، فتواصل مع الدعم مع تزويدهم بهذا السياق.

​
قبل التواصل مع الدعم

التقط هذه التفاصيل أولاً:
  • طريقة HTTP
  • مسار Endpoint
  • اسم Model
  • JSON لهيكل request body بعد تنقيته من البيانات الحساسة (هذا هو العنصر الأكثر فائدة في معظم استدعاءات API)
  • Query parameters إذا كان الطلب الذي فشل يستخدمها
  • response body الكامل إذا كان عميلك قد التقطه
  • حالة HTTP الكاملة
  • قيمة error.message كما هي تمامًا
  • أي request id
  • طابع زمني تقريبي
  • ما إذا كان الطلب نفسه يعمل مع Model آخر أو Token آخر
إذا كان المسار الذي فشل يقبل رفع ملفات (تحرير الصور، رفع الصوت، إنشاء الفيديو، وما إلى ذلك) بدلًا من JSON عادي، فأرسل الحمولة المكافئة التي تم إرسالها:
  • أسماء الحقول والقيم النصية التي أرسلتها مع الملف
  • اسم الملف، ونوعه، وحجمه التقريبي
  • ما إذا كان الملف قد تم رفعه مباشرة، أو تمت الإشارة إليه عبر URL، أو تضمينه بصيغة base64
أسرع طريقة لإعادة إنتاج bug هي حمولة الطلب المنقاة نفسها تمامًا. بالنسبة لمعظم استدعاءات API، فهذا يعني JSON الخام لـ request body. وبالنسبة للمسارات التي تتضمن رفع ملفات، فهذا يعني قائمة الحقول بالإضافة إلى metadata الخاصة بالملف.
هذا يختصر وقت استجابة الدعم بشكل ملحوظ.