الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

تكون معالجة الأخطاء في CometAPI أسهل عندما تفصل بين مشكلات بنية الطلب ومشكلات المصادقة وأخطاء المسار وإخفاقات المنصة القابلة لإعادة المحاولة. استخدم مزيجًا من حالة HTTP وerror.code وerror.message لتحديد ما إذا كان ينبغي إصلاح الطلب أو إعادة محاولته.

​
فرز سريع

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

​
غلاف الخطأ

تستخدم العديد من حالات الفشل في CometAPI نص خطأ مثل هذا: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
تترك بعض الاستجابات الحقل code فارغًا. عندما تكون الحالة 500، اعتبر error.code وerror.message الإشارة الحاسمة.

​
400 Bad Request

يعني 400 عادةً أن نص الطلب فشل في التحقق من الصحة قبل أن تتم معالجة الطلب بشكل طبيعي. الأسباب الشائعة:
  • غياب الحقول المطلوبة مثل model
  • بنية JSON غير صالحة
  • إرسال حقل بنوع غير صحيح
  • إعادة استخدام معلمات خاصة بمزوّد لا يقبلها endpoint المحدد
ابدأ بطلب بسيط معروف بأنه صحيح، ثم أضف الحقول الاختيارية مرةً تلو الأخرى. قارِن الحمولة بمخطط endpoint في مرجع API. استخدم طلبًا بسيطًا مثل هذا: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
استبدل 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: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
إذا كانت استجابة 500 تتضمن error.code: invalid_request، فتعامل معها على أنها مشكلة في الطلب:
  1. أصلح نص الطلب.
  2. قارِن الحمولة بمخطط endpoint.
  3. أعد المحاولة فقط بعد تصحيح الحمولة.
إذا كانت استجابة 500 لا تشير إلى طلب غير صالح، فاحتفِظ بـ request id واستخدم backoff.

​
401 Invalid Token

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

​
403 Forbidden

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

​
عنوان URL الأساسي أو المسار غير صحيح

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

​
413 Request Entity Too Large

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

​
429 Too Many Requests

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

​
503, 504, and 524

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

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

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