> ## 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 وتطبيق خطوات إعادة المحاولة أو الإصلاح لحالات فشل الطلبات الشائعة.

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

## فرز سريع

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

## غلاف الخطأ

تستخدم كثير من حالات فشل CometAPI جسم خطأ مثل هذا:

```json theme={null}
{
	"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.

استخدم طلبًا بسيطًا مثل هذا:

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

استبدل `your-model-id` بأي model ID حالي من [صفحة نماذج CometAPI](/ar/overview/models).

لا تفترض أن كل طلب chat غير صحيح يعيد `400`. فقد تظهر أيضًا الحقول المطلوبة المفقودة في chat مثل `messages` على شكل `500` مع `error.code: invalid_request`.

## `500 Internal Server Error`

تشير معظم استجابات `500` إلى فشل في المنصة أو المزوّد. بالنسبة إلى Chat Completions، قد تظهر بعض الطلبات غير الصحيحة أيضًا على شكل `500` مع استمرار تضمين `error.code: invalid_request`.

أحد الأمثلة هو طلب يحذف `messages`:

```json theme={null}
{
	"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 بهذا الشكل:

```json theme={null}
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
```

ما الذي يجب التحقق منه:

1. يجب أن يكون الـ header بالشكل المطابق تمامًا `Authorization: Bearer $COMETAPI_KEY`.
2. تأكد من أن تطبيقك لا يحمّل مفتاحًا قديمًا من `.env` أو سجل shell أو مخزن secrets منشور.
3. إذا فشل مفتاح واحد ونجح مفتاح آخر مع الطلب نفسه، فاعتبر هذه مشكلة token وليست مشكلة endpoint.

## `403 Forbidden`

غالبًا ما تكون `403` إحدى هذه الحالات:

* تم حظر الطلب بواسطة قاعدة على مستوى المنصة مثل تصفية WAF
* token أو route غير مصرح لهما باستخدام model المطلوب أو شكل الطلب المطلوب
* model المختار يرفض أحد المعلمات المتقدمة التي مررتها

ما الذي يجب فعله أولًا:

1. أعد المحاولة باستخدام طلب نصي بسيط جدًا مع model معروف بأنه يعمل.
2. أزل الحقول المتقدمة والمعلمات الخاصة بـ provider، ثم أعد إضافتها تدريجيًا.
3. إذا كانت الاستجابة تتضمن request id، فاحتفظ به قبل التواصل مع الدعم.

<Warning>
  إذا كانت الرسالة تذكر مصطلحات داخلية مثل `group` أو `channel`، فتعامل معها على أنها تفاصيل توجيه، وليس كأول شيء يجب تشخيصه من جهة العميل. يظل الحل العملي هو التحقق أولًا من token وmodel وشكل الطلب.
</Warning>

## عنوان URL أساسي خاطئ أو مسار خاطئ

في Comet، قد يظهر خطأ في المسار على شكل:

* إعادة توجيه
* استجابة HTML غير JSON إذا كان العميل لديك يتبع عمليات إعادة التوجيه
* خطأ parsing داخل SDK الخاص بك
* طلب لا يصل أبدًا إلى طبقة API بشكل سليم

استخدم عنوان URL الأساسي هذا كما هو تمامًا:

```text theme={null}
https://api.cometapi.com/v1
```

عمليات تحقق موصى بها:

1. تأكد من أن عنوان URL الأساسي يتضمن `/v1`.
2. تأكد من أن مسار endpoint يطابق التوثيق تمامًا.
3. عطّل التتبع التلقائي لعمليات إعادة التوجيه أثناء تصحيح مشكلات المسار.

## `413 Request Entity Too Large`

إذا رأيت `413`، فاعتبرها أولًا مشكلة **حجم الطلب**. من الأسباب الشائعة:

* حمولات base64 كبيرة
* صور أو ملفات صوتية كبيرة جدًا مضمنة inline
* أجسام multipart أو JSON كبيرة جدًا

ما الذي يجب فعله:

1. قلّل حجم المحتوى المرفق أو اضغطه.
2. قسّم المهام الكبيرة إلى طلبات أصغر.
3. لا تفترض أن طول النص العادي هو السبب الوحيد.

## `429 Too Many Requests`

تعامل مع `429` على أنها قابلة لإعادة المحاولة:

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

للاطلاع على نمط قابل لإعادة الاستخدام لإعادة المحاولة، راجع مثال backoff في [Chat Completions](/api/text/chat).

## `503`, `504`, and `524`

هذه الحالات هي **إخفاقات من جهة الخادم أو من فئة المهلة الزمنية**.

إرشادات عملية:

* `503`: route أو خدمة provider غير متاحة مؤقتًا
* `504` و `524`: إخفاقات من فئة المهلة الزمنية بين المنصة أو edge أو خدمة provider

ما الذي يجب فعله:

1. أعد المحاولة باستخدام backoff.
2. احتفظ بـ `request id` وendpoint وmodel والطابع الزمني.
3. إذا تكرر الإخفاق نفسه عبر عدة محاولات إعادة، فتواصل مع الدعم مع تزويدهم بهذا السياق.

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

التقط هذه التفاصيل أولاً:

* طريقة HTTP
* مسار نقطة النهاية
* Model ID
* **JSON لهيئة الطلب بعد تنقيح البيانات الحساسة** (وهذا هو العنصر الأكثر فائدة في معظم استدعاءات API)
* معاملات الاستعلام إذا كان الطلب الذي فشل يستخدمها
* نص هيئة الاستجابة بالكامل إذا كان عميلك قد التقطه
* حالة HTTP الكاملة
* قيمة `error.message` الدقيقة
* أي `request id`
* طابع زمني تقريبي
* ما إذا كان الطلب نفسه يعمل مع model آخر أو token آخر

إذا كان المسار الذي فشل يقبل **رفع الملفات** (تحرير الصور، رفع الصوت، إنشاء الفيديو، إلخ) بدلاً من هيئة JSON عادية، فأرسل الحمولة المكافئة التي تم إرسالها:

* أسماء الحقول والقيم النصية التي أرسلتها مع الملف
* اسم الملف ونوعه وحجم الملف التقريبي
* ما إذا كان الملف قد رُفع مباشرةً، أو تمت الإشارة إليه عبر URL، أو تم تضمينه بصيغة base64

<Warning>
  الطريقة الأكثر فعالية لإعادة إنتاج bug هي حمولة الطلب الدقيقة بعد تنقيح البيانات الحساسة. بالنسبة لمعظم استدعاءات API، فهذا يعني **JSON الخام لهيئة الطلب**. أما بالنسبة للمسارات التي تعتمد على رفع الملفات، فهذا يعني قائمة الحقول بالإضافة إلى بيانات الملف الوصفية.
</Warning>

هذا يقلّص وقت استجابة الدعم بشكل كبير.