# الأخطاء

تفشل كل نقطة نهاية بالطريقة نفسها: حالة HTTP وغلاف JSON واحد.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| الحقل | المعنى |
|---|---|
| `type` | الفئة العامة للخطأ. حدّد الإجراء بناءً عليها. |
| `code` | السبب الدقيق، ثابت وقابل للقراءة آليًا. لكل رمز قسم أدناه؛ ويربط `doc_url` بهذا القسم. |
| `message` | شرح مقروء للبشر، وآمن لتسجيله أو عرضه على مطوّر. |
| `param` | معلمة الإدخال أو الرأس المسبّب للمشكلة، إن وُجد. |
| `details` | في أخطاء الإدخال، كل مشكلة تم العثور عليها: `[{ "param", "message" }]`. |
| `request_id` | الطلب المعني، إن وُجد. |

لا تُحتسب أي رسوم على استدعاء يُرجع خطأً. يظل الطلب الذي يفشل *بعد* قبوله بحالة
`failed`، ويحمل `error: { "type", "code", "message" }` في كائن الطلب، وتُسترد تكلفته تلقائيًا.

## الأنواع

| النوع | حالة HTTP | الإجراء |
|---|---|---|
| `invalid_request` | 400 أو 413 أو 422 | أصلح الطلب. ستفشل إعادة المحاولة بالاستدعاء نفسه مجددًا. |
| `authentication_error` | 401 | أرسل مفتاحًا صالحًا في `Authorization: Bearer <key>`. |
| `permission_error` | 403 | استخدم مفتاحًا بالنطاق المطلوب. |
| `not_found` | 404 | تحقّق من معرّف النموذج أو معرّف الطلب. |
| `insufficient_credits` | 402 | اشحن رصيد API (`top_up_url` في الخطأ). |
| `budget_exceeded` | 402 | استُنفدت ميزانية المفتاح نفسه. نهائيًا: اطلب من مالك المفتاح رفعها. |
| `conflict` | 409 | المورد ليس في حالة تسمح بهذا الاستدعاء. |
| `rate_limited` | 429 | انتظر `Retry-After` ثانية، ثم أعد المحاولة. |
| `upstream_error` | 502 | فشل نظام النموذج الخلفي. من الآمن إعادة المحاولة باستخدام `Idempotency-Key` نفسه: سيُشغّل مجددًا؛ ولم تُفرض عليك رسوم. |
| `service_unavailable` | 503 | API متوقف مؤقتًا أو إحدى التبعيات متوقفة. أعد المحاولة لاحقًا. |
| `internal_error` | 500 | خطأ من جانبنا. أعد المحاولة؛ وإذا استمر، تواصل مع الدعم مرفقًا بالوقت و`request_id`. |

## الرموز

### `invalid_request`

طلب عام غير صحيح البنية (400).

### `invalid_json`

النص ليس JSON صالحًا (400).

### `invalid_body`

النص JSON صالح لكنه ليس كائنًا؛ يجب أن يكون مدخل النموذج كائن JSON (400).

### `body_too_large`

النص أكبر من 16 MB (413). ارفع الملفات الكبيرة ومرّر عنوان URL الخاص بها بدلًا من ذلك (راجع [الملفات](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

تحتوي معلمة استعلام على قيمة غير صحيحة، مثل `limit` خارج النطاق من 1 إلى 100، أو `wait` ليست رقمًا، أو `status` أو `category` غير معروفة، أو `storage` غير `permanent` / `temporary` (400). يحدّد `param` اسمها.

### `invalid_category`

يحدّد `GET /openapi.json?category=` فئة غير موجودة (400). يسردها `GET https://api.doitong.ru/v1/categories`.

### `invalid_cursor`

لا ينتمي `cursor` الخاص باستدعاء قائمة إلى هذه القائمة (400). ابدأ مجددًا من دون مؤشر.

### `invalid_idempotency_key`

رأس `Idempotency-Key` فارغ أو أطول من 255 محرفًا (400).

### `invalid_arguments`

يحتوي استدعاء أداة MCP على وسيطة مفقودة أو غير صحيحة البنية (MCP فقط). يحدّد `param` اسم الوسيطة.

### `invalid_input`

لا يجتاز مدخل النموذج التحقق (422): معلمة غير معروفة (تقترح الرسالة أقرب اسم صالح)، أو معلمة مطلوبة مفقودة، أو نوع غير صحيح، أو قيمة خارج القائمة أو النطاق المسموح به، أو ورود الاسم الأساسي والاسم الأصلي معًا بقيم مختلفة. تمثل `param` أول معلمة مخالفة، وتسرد `details` جميع المعلمات. لا تُفرض أي رسوم.

### `unsupported_file`

يحتوي ملف على نوع لا نقبله (422)، مثل رفع بامتداد غير مدعوم، أو `content_type` لا يطابق الامتداد.

### `invalid_webhook_url`

`webhook_url` ليس عنوان URL عامًا يبدأ بـ `https://` (422). تُرفض العناوين الخاصة والمحلية والعناوين العادية التي تبدأ بـ `http://`.

### `missing_api_key`

تحتاج نقطة النهاية إلى مفتاح API ولم يُرسل أي مفتاح (401).

### `invalid_api_key`

المفتاح غير معروف أو ملغى أو منتهي الصلاحية (401).

### `insufficient_scope`

يفتقر المفتاح إلى النطاق الذي يحتاجه هذا الاستدعاء (403)، مثل `models:run` للتشغيل، أو `models:read` لقراءة الطلبات والرصيد. راجع [المصادقة](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

الحساب مغلق أو معلّق (403). لم تعد مفاتيحه تعمل.

### `not_found`

المسار غير موجود (404).

### `model_not_found`

لا يوجد نموذج عام بهذا المعرّف (404). اسرد النماذج باستخدام `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

لا يوجد في حسابك طلب بهذا المعرّف (404). لا تظهر طلبات الحسابات الأخرى مطلقًا.

### `insufficient_credits`

لا يغطي **رصيد API** في الحساب (أرصدة API، 1,000 رصيد API = ⁨‏1 $⁩ — وليس رصيد تطبيقات Doitong) تكلفة هذا الاستدعاء (402). تُرسل الاستجابة قبل فرض أي رسوم. يحتوي الخطأ على `top_up_url`؛ أضف المال من [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) ثم أعد المحاولة.

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.ru/developers/dashboard#balance",
             "top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

سيتجاوز الاستدعاء ميزانية مفتاح API نفسه بأرصدة API (402). يحدّد مالك المفتاح الميزانية؛ ولن تفيد إعادة المحاولة حتى يرفعها.

### `conflict`

يتعارض الاستدعاء مع الحالة الحالية للمورد (409).

### `idempotency_mismatch`

استُخدم `Idempotency-Key` من قبل مع نص مختلف (409). استخدم مفتاحًا جديدًا لعملية جديدة.

### `idempotency_in_progress`

يجري الآن إنشاء طلب باستخدام `Idempotency-Key` نفسه (409). أعد المحاولة بعد لحظة للحصول عليه.

### `request_active`

لا يزال الطلب `queued` أو `running`، لذا لا توجد ملفات لحذفها بعد (409). احذفها بعد انتهائه.

### `not_cancelable`

الطلب `succeeded` أو `failed` بالفعل، ولا يمكن إلغاؤه (409).

### `rate_limited`

أجرى المفتاح عددًا كبيرًا من الطلبات في النافذة الحالية (429). راجع رأسي `X-RateLimit-*` و`Retry-After`.

### `too_many_inflight`

لدى الحساب 10 طلبات `queued` أو `running` بالفعل (429). ابدأ الطلب التالي عند انتهاء أحدها.

### `upstream_error`

رفض نظام النموذج الخلفي الطلب أو فشل فيه (502 عند التشغيل، أو `failed` بهذا الرمز في الطلب). تُسترد أرصدة API. إذا رفض النظام الخلفي المدخل نفسه، يُرجع الاستدعاء `422 invalid_input` مع رسالته بدلًا من ذلك.

### `upstream_lost`

لم يعد نظام النموذج الخلفي يعرف الطلب، لذا لن تصل أي نتيجة مطلقًا. ينتهي بحالة `failed` مع هذا الرمز (النوع `upstream_error`) وتُسترد تكلفته. شغّله مجددًا.

### `timeout`

استمر الطلب مدة أطول من حده (15 دقيقة للصور، و60 للفيديو، و30 لغير ذلك) وأُوقف. ينتهي بحالة `failed` مع هذا الرمز وتُسترد تكلفته.

### `service_unavailable`

توقف API مؤقتًا، أو توقفت تبعية مثل رفع الملفات (503). أعد المحاولة لاحقًا.

### `internal_error`

حدث خلل من جانبنا (500). أعد المحاولة؛ وإذا استمر، تواصل مع الدعم.

### `charge_failed`

تعذّر فرض الرسوم على الحساب بسبب مشكلة داخلية (500). يُعلّم الطلب بحالة `failed`؛ ولم يُخصم شيء. أعد المحاولة.

### `pricing_unavailable`

لم يُضبط سعر النموذج، لذا لا يمكن عرض سعره أو تشغيله الآن (500).