# الأخطاء

بنية الخطأ:

```
{ "error": { "code": "...", "message": "...", "retry_after": 12 },

  "meta": { "request_id": "...", "api_version": "v1", "edge": true } }
```

الحقلان `meta.request_id` و`meta.api_version` موجودان دائمًا. أما `retry_after` فيظهر مع `429` فقط. والحقل `meta.edge` يكون `true` فقط عندما تكتب البوابة في `api.dzbuild.app` الرد بنفسها، كرفض المصادقة أو تجاوز حد المعدل أو فشل التحقق من المفتاح، بدلًا من تمرير رد المنصة كما هو.

| الكود                   | HTTP | المعنى                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthorized`          | 401  | رأس Authorization مفقود أو غير صالح                                                                                                                                                                                                                                                                              |
| `forbidden`             | 403  | موثَّق ولكن يفتقر إلى الصلاحية، أو إلى تسجيل في البرنامج التجريبي، أو إلى خطة Enterprise سارية (مفاتيح API الخاصة بالتاجر تتطلب Enterprise، أما رموز التطبيقات المثبّتة فتعمل مع كل الخطط). ويتلقاه رمز التطبيق أيضًا، مع الرسالة `Apps cannot use this endpoint`، على `/v1/keys` و`/v1/webhooks` و`/v1/changes` |
| `app_uninstalled`       | 403  | رمز تطبيق: التطبيق لم يعد مثبّتًا على هذا المتجر                                                                                                                                                                                                                                                                 |
| `app_suspended`         | 403  | رمز تطبيق: علّقت DZBuild التطبيق أو رفضته                                                                                                                                                                                                                                                                        |
| `app_not_approved`      | 403  | رمز تطبيق: التطبيق في وضع الاختبار، وهذا المتجر لا يعود إلى مطوّره                                                                                                                                                                                                                                               |
| `app_plan_required`     | 403  | رمز تطبيق: خطة المتجر أدنى من الخطة الدنيا التي يشترطها التطبيق؛ تذكر `message` اسم الخطة                                                                                                                                                                                                                        |
| `not_found`             | 404  | المورد غير موجود أو لا ينتمي إلى متجرك                                                                                                                                                                                                                                                                           |
| `bad_request`           | 400  | خطأ في التحقق؛ راجع `message`                                                                                                                                                                                                                                                                                    |
| `idempotency_key_reuse` | 422  | سبق استعمال `Idempotency-Key` مع طريقة أو مسار أو محتوى مختلف؛ أرسل مفتاحًا جديدًا                                                                                                                                                                                                                               |
| `method_not_allowed`    | 405  | المسار موجود لكن لطريقة HTTP أخرى                                                                                                                                                                                                                                                                                |
| `payload_too_large`     | 413  | جسم الطلب أكبر من 1 ميغابايت                                                                                                                                                                                                                                                                                     |
| `rate_limited`          | 429  | تجاوز الحد لكل دقيقة؛ يُرفق رأس `Retry-After`. ولرموز التطبيقات أيضًا حد خاص بكل تثبيت قدره 120 طلبًا في الدقيقة، يُفحَص قبل حد المتجر                                                                                                                                                                           |
| `too_many_concurrent`   | 429  | عدد كبير من النداءات المكلفة قيد التنفيذ (الصور، توليد الذكاء الاصطناعي، نداءات شركات التوصيل، كتابات أقسام الصفحة الرئيسية)؛ أعد المحاولة بعد ثوانٍ                                                                                                                                                             |
| `quota_exceeded`        | 402  | تم بلوغ الحد الشهري؛ ارقَ إلى خطة أعلى أو انتظر                                                                                                                                                                                                                                                                  |
| `server_error`          | 500  | خطأ غير متوقع في الخادم؛ آمن لإعادة المحاولة على النداءات الـ idempotent                                                                                                                                                                                                                                         |
| `server_error`          | 502  | تعذّر على `api.dzbuild.app` التحقق من مفتاحك لدى المنصة؛ أعد المحاولة بعد لحظات                                                                                                                                                                                                                                  |

كائن `details` محجوز لإخراج تحقُّق مُهيكَل مستقبلًا. لا توجد نقطة نهاية تُصدره اليوم، فلا تبنِ منطقك عليه.

## إعادة محاولة عملية كتابة فاشلة[​](#إعادة-محاولة-عملية-كتابة-فاشلة "رابط مباشر إلى إعادة محاولة عملية كتابة فاشلة")

تُخزَّن استجابة `4xx` الصادرة عن معالج عملية كتابة مقابل `Idempotency-Key` الخاص بك لمدة 24 ساعة، على `https://api.dzbuild.app` وعلى الاسم البديل `dzbuild.com/api/v1` على حد سواء: إعادة المحاولة بالمفتاح نفسه والمحتوى نفسه تعيد الخطأ ذاته موسومًا بـ`Idempotency-Replay: 1`، دون تنفيذ أي شيء من جديد. صحِّح الطلب وأرسله بمفتاح **جديد**، فالمفتاح القديم يجيب بـ `422 idempotency_key_reuse` على المحتوى المعدَّل. أما حالات الرفض التي تقع قبل تشغيل المعالج، ومنها `401` وردود `403` الخاصة بالبرنامج التجريبي والخطة ورموز `app_*`، و`429`، وغياب `Idempotency-Key` أو خطأ تنسيقه، فلا تُخزَّن، وكذلك استجابات `5xx`، لذا يمكن إعادة المحاولة بالمفتاح نفسه بأمان. انظر [Idempotency](https://dzbuild.com/ar/ar/api-docs/idempotency.md).

أرفق `meta.request_id` دائمًا عند التواصل مع الدعم.