# الأخطاء وحدود معدل الطلبات

تستخدم أخطاء KolWrite API استجابات JSON تتضمن `code` ثابتًا كلما كان بإمكان
العميل اتخاذ إجراء.

```json
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'jobs:write' scope",
    "required_scope": "jobs:write"
  }
}
```

## الحالات الشائعة

| الحالة | المعنى |
|---|---|
| `400` | إدخال غير صالح أو مجموعة خيارات غير مدعومة |
| `401` | رمز وصول مفقود أو غير صالح أو منتهي الصلاحية أو ملغى |
| `403` | رمز الوصول صالح، لكنه يفتقر إلى النطاق المطلوب أو صلاحية الوصول إلى المسار |
| `404` | المورد مفقود أو غير مرئي لمالك رمز الوصول |
| `409` | تعارض، يكون عادةً متعلقًا بالتكرار الآمن أو بانتقال الحالة |
| `422` | بنية محتوى الطلب هي JSON صالحة، لكنها لا تجتاز التحقق |
| `429` | تجاوز حد معدل الطلبات أو ضغط حجز الرصيد |
| `5xx` | خطأ مؤقت في خدمة KolWrite |

## إرشادات إعادة المحاولة

أعد محاولة الطلبات التي تعيد `429` و`502` و`503` و`504` باستخدام تأخير أُسّي مع تفاوت عشوائي.
استخدم `Idempotency-Key` عند إنشاء المهمة كي لا تنشئ إعادات المحاولة عبر الشبكة
مهام مكررة. لا تعد محاولة الطلبات التي تعيد `401` أو `403` أو أخطاء التحقق حتى يُصحح
رمز الوصول أو الطلب.