# الأخطاء

تجمع هذه الصفحة الأخطاء الموصوفة في بقية الصفحات لتعالجها في مكان واحد. ترد الواجهة على كل خطأ بغلاف `JSON` واحد، أما نقاط `OAuth` فتستخدم صيغة `RFC 6749`.

## غلاف الخطأ في الواجهة[​](#غلاف-الخطأ-في-الواجهة "رابط مباشر إلى غلاف الخطأ في الواجهة")

```
{

  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },

  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }

}
```

`error.code` ثابت ومخصص لبرنامجك. `error.message` موجه للبشر وقد يتغير. اذكر `meta.request_id` عندما تراسل `DZBuild` بخصوص استدعاء ما. تضيف بعض الأخطاء حقولاً داخل `error`، مثل `retry_after` في الرد `429`.

## أكواد حالة الواجهة[​](#أكواد-حالة-الواجهة "رابط مباشر إلى أكواد حالة الواجهة")

| الحالة | `error.code`                | الرسالة                                                            | السبب والإجراء                                                                                                                                                                                                                                                                       |
| ------ | --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `bad_request`               | متغيرة                                                             | ترويسة `Idempotency-Key` مفقودة أو غير صحيحة في طلب `POST` أو `PATCH` أو `DELETE`، أو المتن ليس `JSON` صالحاً، أو معرّف في المسار ليس رقماً. صحّح الطلب وأرسل مفتاحاً جديداً.                                                                                                        |
| `401`  | `unauthorized`              | `Missing Authorization header`                                     | لا توجد ترويسة `Authorization`.                                                                                                                                                                                                                                                      |
| `401`  | `unauthorized`              | `Unsupported Authorization scheme`                                 | الترويسة لا تبدأ بـ `Bearer`.                                                                                                                                                                                                                                                        |
| `401`  | `unauthorized`              | `Invalid or revoked API key`                                       | الرمز خاطئ، أو أزال التاجر تطبيقك. تعامل معه كإزالة ما لم تكن متأكداً من غير ذلك.                                                                                                                                                                                                    |
| `402`  | `no_credit`                 |                                                                    | محفظة `WhatsApp` في المتجر فارغة. لم يُصطف شيء ولم يُخصم شيء. إعادة المحاولة لا تفيد؛ يعبّئ التاجر الرصيد من لوحة التحكم.                                                                                                                                                            |
| `402`  | `quota_exceeded`            |                                                                    | بلغ المتجر حصة شهرية من الطلبات حددتها `DZBuild` له. إعادة المحاولة لا تفيد.                                                                                                                                                                                                         |
| `403`  | `forbidden`                 | `Missing scope: <scope>`                                           | الرمز لا يحمل الصلاحية التي تحتاجها نقطة الوصول. بعض عمليات الكتابة تحتاج صلاحية القراءة أيضاً؛ انظر [الصلاحيات](https://dzbuild.dev/ar/ar/scopes.md).                                                                                                                               |
| `403`  | `forbidden`                 | `Apps cannot use this endpoint`                                    | `/v1/keys` و`/v1/webhooks` و`/v1/changes` مغلقة أمام رموز التثبيت.                                                                                                                                                                                                                   |
| `403`  | `app_uninstalled`           | `This app is no longer installed on this store`                    | التثبيت لم يعد نشطاً. توقف عن استخدام الرمز واحذف بيانات المتجر.                                                                                                                                                                                                                     |
| `403`  | `app_suspended`             | `This app has been suspended by DZBuild`                           | أوقفت `DZBuild` التطبيق أو رفضته. تعود الاستدعاءات إلى العمل بعد رفع الإيقاف.                                                                                                                                                                                                        |
| `403`  | `app_not_approved`          | `This app is in test mode and only runs on its developer's stores` | لم يُقبل التطبيق بعد والمتجر ليس ملكك.                                                                                                                                                                                                                                               |
| `403`  | `app_plan_required`         | `This app requires the ... plan`                                   | خطة المتجر، أو خطة مدفوعة منتهية، أدنى من الخطة الدنيا للتطبيق. أخبر التاجر بالخطة المطلوبة.                                                                                                                                                                                         |
| `403`  | `addon_not_active`          |                                                                    | خاص بـ `WhatsApp`. لم يفعّل التاجر إضافة `WhatsApp Sender`.                                                                                                                                                                                                                          |
| `403`  | `plan_required`             |                                                                    | خاص بأقسام الصفحة الرئيسية. الكتابة تترك أقساماً أكثر مما تسمح به خطة المتجر. يحمل `error` قيمتي `plan` و`cap`.                                                                                                                                                                      |
| `404`  | `not_found`                 |                                                                    | لا يوجد سجل بهذا المعرّف في هذا المتجر.                                                                                                                                                                                                                                              |
| `404`  | `section_not_found`         |                                                                    | خاص بأقسام الصفحة الرئيسية. لا يوجد قسم بهذا الرقم في الصفحة الرئيسية للمتجر.                                                                                                                                                                                                        |
| `409`  | `already_sent`              |                                                                    | خاص بـ `WhatsApp`. أُرسل هذا القالب من قبل لهذا الطلب. يحمل `error` قيمتي `id` و`status` للرسالة الموجودة.                                                                                                                                                                           |
| `409`  | `write_conflict`            |                                                                    | خاص بأقسام الصفحة الرئيسية. غيّرت كتابة أخرى التخطيط قبلك، أو `version` المرسلة مع `PUT` ليست الحالية. عندما يحمل `error` قيمتي `sections` و`version` أعد المحاولة انطلاقاً منهما، وإلا فاقرأ التخطيط من جديد.                                                                       |
| `422`  | `idempotency_key_reuse`     |                                                                    | أُرسل المفتاح `Idempotency-Key` نفسه بطريقة أو مسار أو متن مختلف. مفتاح واحد لكل عملية.                                                                                                                                                                                              |
| `422`  | أكواد `WhatsApp`            |                                                                    | `unknown_template` و`invalid_language` و`invalid_number` و`suppressed` و`template_not_approved` و`empty_param`. لم يُخصم شيء. صحّح السبب وأعد الاستدعاء بمفتاح جديد. انظر [واجهة WhatsApp](https://dzbuild.dev/ar/ar/whatsapp.md).                                                   |
| `422`  | أكواد أقسام الصفحة الرئيسية |                                                                    | `invalid_settings` (تذكر `error.fields` الإعدادات المرفوضة، ومع `PUT` إعدادات أول قسم مرفوض) و`invalid_section_type` و`limit_reached` و`invalid_order` و`no_changes`. صحّح الطلب وأعد الاستدعاء بمفتاح جديد. انظر [أقسام الصفحة الرئيسية](https://dzbuild.dev/ar/ar/home-layout.md). |
| `429`  | `rate_limited`              | `Per-minute API limit exceeded for this app install`               | نفدت ميزانية تثبيتك، 120 طلباً في الدقيقة. انتظر `retry_after` ثانية (موجودة أيضاً في ترويسة `Retry-After`) ثم أعد الإرسال بالمفتاح `Idempotency-Key` نفسه.                                                                                                                          |
| `429`  | `rate_limited`              | `Per-minute API limit exceeded for this store`                     | نفدت ميزانية المتجر المشتركة. المعالجة نفسها.                                                                                                                                                                                                                                        |
| `429`  | `rate_limited`              | `Per-minute API limit exceeded for this key`                       | سقف البوابة، 600 طلب في الدقيقة لكل متجر. المعالجة نفسها.                                                                                                                                                                                                                            |
| `429`  | `too_many_concurrent`       |                                                                    | عمليات مكلفة كثيرة في الوقت نفسه (رفع الصور، استدعاءات شركات التوصيل، كتابات أقسام الصفحة الرئيسية). قيمة `retry_after` هي 5 ثوانٍ.                                                                                                                                                  |
| `500`  | `send_failed`               |                                                                    | خاص بـ `WhatsApp`. تعذّر اصطفاف الرسالة. أعد المحاولة لاحقاً.                                                                                                                                                                                                                        |
| `502`  | `server_error`              | `Key lookup failed, retry shortly`                                 | لم تستطع البوابة التحقق من الرمز لدى `DZBuild`. أعد المحاولة بعد انتظار قصير بالمفتاح `Idempotency-Key` نفسه.                                                                                                                                                                        |

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

| الرد                              | إعادة المحاولة                                                                 | باستخدام                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `429`                             | نعم، بعد `retry_after` ثانية                                                   | المفتاح `Idempotency-Key` نفسه                                                |
| `5xx` و`502`                      | نعم، بعد انتظار قصير                                                           | المفتاح `Idempotency-Key` نفسه؛ هذه الردود لا تُحفظ أبداً، لذلك يُنفَّذ الطلب |
| `400` و`401` و`403` و`404` و`422` | لا. صحّح السبب أولاً                                                           | مفتاح `Idempotency-Key` جديد، لأن الرد `4xx` المحفوظ يُعاد لمدة 24 ساعة       |
| `402`                             | لا. على التاجر أن يتصرف                                                        |                                                                               |
| `409 already_sent`                | لا. الرسالة موجودة                                                             |                                                                               |
| `409 write_conflict`              | نعم، انطلاقاً من `sections` و`version` في `error` أو بعد قراءة التخطيط من جديد | مفتاح `Idempotency-Key` جديد                                                  |

## أخطاء OAuth[​](#أخطاء-oauth "رابط مباشر إلى أخطاء OAuth")

قبل أن تطابق `DZBuild` قيمتي `client_id` و`redirect_uri`، تعرض صفحة خطأ للتاجر ولا تعيد التوجيه أبداً. بعد ذلك تعيد التوجيه إلى `redirect_uri` مع معامل `error`:

| `error`                     | السبب                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `unsupported_response_type` | قيمة `response_type` ليست `code`.                                                                                             |
| `invalid_request`           | `state` مفقود أو أطول من 1024 حرفاً، أو `code_challenge` ليس 43 حرفاً بصيغة base64url، أو `code_challenge_method` ليس `S256`. |
| `invalid_scope`             | صلاحية غير مسجلة على التطبيق أو غير مسموح بها للتطبيقات، أو معامل `scope` أطول من 512 حرفاً.                                  |
| `access_denied`             | ضغط التاجر على رفض.                                                                                                           |

ترد نقطة الرمز بصيغة `JSON` تحمل `error` و`error_description`:

| HTTP  | `error`                    | السبب                                                                                                                                                      |
| ----- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | `invalid_client`           | `client_id` أو `client_secret` مفقود أو خاطئ.                                                                                                              |
| `400` | `unsupported_grant_type`   | قيمة `grant_type` ليست `authorization_code`.                                                                                                               |
| `400` | `invalid_grant`            | كود مجهول أو منتهٍ أو مستعمل، أو كود صادر لتطبيق آخر، أو `redirect_uri` مختلف، أو مُحقِّق لا يطابق التحدي، أو تعذّر تثبيت أي متجر من المتاجر المختارة.     |
| `500` | `server_error`             | عطل في المنصة. أعد توجيه التاجر إلى خطوة التفويض من جديد.                                                                                                  |
| `403` | لا يوجد، الجسم صفحة `HTML` | الطلب لا يحمل الترويسة `User-Agent`، و`dzbuild.com` يجيب على أي طلب `POST` بدونها بصفحة تحقق بدل `JSON`. أرسلها، مثلا `my-app/1.0 (+https://example.com)`. |

الكود الذي طُلب استبداله يُستهلك حتى لو فشل التبادل، لذلك ابدأ طلب تفويض جديداً بدل إعادة المحاولة بالكود نفسه. الترتيب الكامل للفحوص وصفحات الخطأ في صفحة [OAuth](https://dzbuild.dev/ar/ar/oauth.md).

## إخفاقات إرسال إشعارات webhook[​](#إخفاقات-إرسال-إشعارات-webhook "رابط مباشر إلى إخفاقات إرسال إشعارات webhook")

ينجح الإرسال عندما يرد خادمك بـ `2xx` خلال 10 ثوانٍ. أي حالة أخرى، أو إعادة توجيه، أو انتهاء مهلة، أو خطأ اتصال يُعدّ محاولة فاشلة. تحاول `DZBuild` كل إرسال حتى 5 مرات بفترات انتظار متزايدة، ثم تعلّمه كمتروك. بعد 10 محاولات فاشلة متتالية على تثبيت واحد يُعطَّل رابطه؛ اضغط على تحقق في منصة المطورين لإعادة تفعيله. التفاصيل والجدول في صفحة [إشعارات Webhook](https://dzbuild.dev/ar/ar/webhooks.md).

يجب أن يرد تحققك أنت بـ `401` عندما يفشل التوقيع أو فحص الطابع الزمني. ولأن ذلك ليس رداً `2xx`، تعدّه `DZBuild` محاولة فاشلة وتعيد المحاولة؛ الطلب الذي يفشل في التحقق دائماً ليس من `DZBuild`، أو أن سرّ التوقيع لديك قديم.