# أخطاء API ورموز الحالة

> ما يعنيه كل رمز حالة HTTP ورمز خطأ من واجهة API في عليا بوكس وكيفية التعامل معه.

Source: /help/ar/api/error-handling

كل خطأ في API هو نص JSON بالشكل نفسه، لذا يكفي معالج واحد لتغطيتها جميعاً:

```json
{ "code": "E_VALIDATION", "statusCode": 400, "message": "…", "field": "items", "extra": { … } }
```

`code` هو السبب المقروء آلياً، ويشير `field` إلى المدخل المخالف عند وجوده، ويحمل `extra` تفاصيل مثل أخطاء PINT AE أو نتائج الدفعات.

## رموز الحالة

| الحالة | الرمز | المعنى | ما يجب فعله |
|---|---|---|---|
| 400 | `E_VALIDATION` | الحمولة غير صالحة أو الفاتورة لا تجتاز فحص PINT AE | صحّح الحقل المذكور في `field`؛ واقرأ `extra.errors` لمعرفة مصطلحات الأعمال |
| 401 | `UNAUTHORIZED` | مفتاح مفقود أو مشوّه أو غير معروف أو مُبطل أو منتهي الصلاحية | راجع مقالة 401 |
| 403 | `FORBIDDEN` | المفتاح يفتقر إلى النطاق، أو `X-Organization-Id` ليس عميلاً مُداراً | أنشئ مفتاحاً بالنطاقات الصحيحة |
| 404 | `NOT_FOUND` | لا توجد فاتورة أو عملية استيراد أو عميل أو ملف بهذا المعرّف | تحقق من المعرّف |
| 409 | `CONFLICT` | الإجراء غير مسموح به في الحالة الحالية، مثل حذف فاتورة مقبولة أو إعادة استخدام SKU | غيّر الحالة أولاً (الأرشفة بدلاً من الحذف) |
| 413 | `PAYLOAD_TOO_LARGE` | الملف المرفوع يتجاوز 20 ميغابايت | قسّمه أو اضغطه |
| 422 | `E_VALIDATION` | فشل التحقق من مستند مستلم عند الاستيراد | يُسجَّل الاستيراد؛ اقرأ `extra.validation` |
| 429 | `RATE_LIMITED` | أكثر من 600 طلب في الدقيقة لهذا المفتاح | انتظر عدد الثواني المذكور في `Retry-After` |
| 503 | `SERVICE_UNAVAILABLE` | طُلب ملف PDF لعرض فاتورة واردة في بيئة لا توجد فيها خدمة تحويل HTML إلى PDF (ملفات PDF للفواتير والإشعارات الدائنة والمدينة والفواتير المبدئية تعمل دائماً) | اطلب `?format=html` أو `xml` |
| 500 | `INTERNAL_SERVER_ERROR` | فشل غير متوقع | أعد المحاولة؛ وتواصل مع support@alyabooks.ai مع ذكر `X-Request-Id` |

## الدفعات

عندما تفشل فاتورة واحدة في دفعة، تأخذ الاستجابة حالة أول فشل (عادةً 400) ويسرد `extra.results` كل عنصر مع `index` و`success` والخطأ الخاص به. العناصر التي تحمل `success: true` أُنشئت؛ فأعد المحاولة للعناصر الأخرى فقط.

## معلومات مفيدة

- تحمل كل استجابة `X-Request-Id`، وتكرره رسائل الخطأ في الحقل `requestId`. وتعرض علامة التبويب **Recent requests** (الطلبات الأخيرة) في صفحة API access المعرّف نفسه تحت كل طلب مع الحالة والتوقيت.
- تُعاد محاولة تسليم webhooks بعد دقيقة و5 دقائق و30 دقيقة وساعتين و12 ساعة على الأقل (ترسل إعادات المحاولة مهمةٌ تعمل كل 5 دقائق)؛ ويعرض مربع حوار عمليات التسليم المحاولات ويتيح لك إعادة المحاولة يدوياً.

## مقالات ذات صلة

- [لماذا أحصل على 401 عند استدعاء API؟](/help/ar/api/401-troubleshooting)
- [الحقول المطلوبة عند إنشاء الفواتير عبر API](/help/ar/api/required-fields)