> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chattler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# الأخطاء

> غلاف واحد، ورموز ثابتة، ومعرّف طلب في كل رد.

## الغلاف

كل إخفاق، أيًا كانت الحالة، هو كائن JSON واحد:

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"
  }
}
```

* `code` ثابت وقابل للقراءة آليًا. تفرّع عليه لا على `message`.
* `message` شرح مقروء للبشر وقد يتغير.
* `request_id` هو UUID الطلب. يُعاد أيضًا في الترويسة `X-Request-ID` في **كل** رد، نجاحًا كان أم فشلًا. اذكره عند الإبلاغ عن مشكلة.

في نقطة نهاية الرد المتدفق، الإخفاق الذي يحدث بعد بدء التدفق يصل كحدث `error` بنفس الحقول الثلاثة؛ راجع [الرد المتدفق](/ar/guides/streaming).

## الرموز

| HTTP | الرمز                        | المعنى                                                                                               |
| ---- | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| 401  | `invalid_api_key`            | مفتاح مفقود أو مشوّه أو مجهول أو محذوف أو بسر خاطئ                                                   |
| 403  | `agent_mismatch`             | المفتاح ينتمي إلى وكيل آخر                                                                           |
| 403  | `permission_denied`          | مفتاح `read-only` استدعى نقطة نهاية دردشة                                                            |
| 403  | `agent_disabled`             | الوكيل مُطفأ. نقطتا نهاية الدردشة فقط                                                                |
| 404  | `agent_not_found`            | الوكيل لم يعد موجودًا. نقطتا نهاية الدردشة فقط                                                       |
| 404  | `conversation_not_found`     | محادثة مجهولة، أو ليست لهذا المفتاح                                                                  |
| 402  | `insufficient_balance`       | رصيد المالك لا يغطي الرد؛ لم يُخصم شيء                                                               |
| 409  | `idempotency_conflict`       | استُخدم نفس `Idempotency-Key` بجسم مختلف                                                             |
| 409  | `idempotency_in_progress`    | الطلب الأصلي ما زال جاريًا؛ أعد المحاولة بعد ثواني `Retry-After` (دائمًا `2`)                        |
| 409  | `conversation_busy`          | رسالة أخرى للمستخدم الخارجي نفسه قيد الإجابة؛ أعد المحاولة بعد `Retry-After` (دائمًا `2`)            |
| 422  | `validation_error`           | جسم أو ترويسة أو تاريخ أو حد أو مؤشر غير صالح                                                        |
| 429  | `rate_limit_exceeded`        | نافذة المفتاح مستنفدة؛ راجع [حدود المعدل](/ar/guides/rate-limits)                                    |
| 503  | `api_rate_limit_unavailable` | محدّد المعدل متوقف؛ يُرفض الطلب بدلًا من خدمته بلا قياس. أعد المحاولة بعد `Retry-After` (دائمًا `5`) |
| 503  | `service_unavailable`        | خدمة خلفية تعتمد عليها API متوقفة؛ أعد المحاولة بعد `Retry-After` (دائمًا `2`)                       |
| 500  | `internal_error`             | إخفاق غير متوقع؛ اذكر `request_id`                                                                   |

يُفحص `agent_not_found` و`agent_disabled` فقط في `POST …/chat` و`POST …/chat/stream`. نقطتا نهاية `GET` لا تنظران إلى حالة الوكيل: مفتاح وكيل معطّل ما زال يستطيع عرض محادثاته وقراءة رسائله.

## ما الذي يُعاد محاولته

<AccordionGroup>
  <Accordion title="أعد المحاولة بعد Retry-After بنفس Idempotency-Key">
    `idempotency_in_progress`، `conversation_busy`، `rate_limit_exceeded`، `api_rate_limit_unavailable`، `service_unavailable`. إعادة استخدام المفتاح تضمن ألا تدفع مرتين للرسالة نفسها.
  </Accordion>

  <Accordion title="أصلح الطلب أولًا">
    `validation_error` (اقرأ `message`؛ فهي تسمّي الحقل المخالف)، `idempotency_conflict` (استخدم مفتاحًا جديدًا للجسم الجديد)، `permission_denied` (استخدم مفتاح `full`)، `agent_mismatch` (استخدم الوكيل الذي ينتمي إليه المفتاح).
  </Accordion>

  <Accordion title="لا تعد المحاولة تلقائيًا">
    `invalid_api_key` (المفتاح حُذف أو السر خاطئ)، `agent_disabled`، `agent_not_found`، `insufficient_balance` (اشحن الرصيد أولًا). حلقة إعادة المحاولة على هذه الرموز لا تفعل سوى استنزاف حد المعدل.
  </Accordion>

  <Accordion title="أبلغ مع معرّف الطلب">
    `internal_error`. أعد المحاولة مرة واحدة بنفس `Idempotency-Key`: السجل الفاشل يُحرَّر، فتشغّل إعادة المحاولة الطلب من جديد بدلًا من إعادة نتيجة مخزّنة. هذا متوقع، لكنه ليس مضمونًا أن يكون مجانيًا. إذا حدث الإخفاق بعد أن أجاب النموذج بالفعل، تنتج إعادة المحاولة ردًا جديدًا وخصمًا جديدًا. إذا استمر الإخفاق، أرسل إلينا `request_id`.
  </Accordion>
</AccordionGroup>

## ملاحظة حول 401

لا تفرّق API بين مفتاح محذوف ومفتاح لم يوجد قط: كلاهما `invalid_api_key`. إذا بدأ مفتاح كان يعمل بإرجاع 401، تحقق من بطاقة الوصول عبر API في التطبيق؛ فالأرجح أنه دُوِّر أو حُذف.