# حدود معدّل الطلبات

كل طلب يُرسل برمز تثبيت يمرّ على عدّادين في الدقيقة: عدّاد تثبيتك، ثم عدّاد المتجر. وتحتاج عمليات الكتابة أيضًا إلى ترويسة `Idempotency-Key` حتى لا تُنفَّذ إعادة المحاولة مرتين.

## حصة التثبيت[​](#حصة-التثبيت "رابط مباشر إلى حصة التثبيت")

لكل تثبيت لتطبيقك حصته الخاصة: 120 طلبًا في الدقيقة. تُفحص هذه الحصة أولًا، فالتطبيق الذي يدور في حلقة على متجر واحد يبلغ حدّه الخاص قبل أن يستنفد حصة متجر التاجر.

العدّاد نافذة ثابتة تبدأ من الصفر مع بداية كل دقيقة على الساعة. كل طلب يُحسب، بما في ذلك الطلبات الفاشلة. والطلبات المرفوضة بـ `429` تُحسب أيضًا، فإعادة المحاولة في حلقة سريعة لا تقرّب موعد التصفير.

## حصة المتجر[​](#حصة-المتجر "رابط مباشر إلى حصة المتجر")

بعد حصة التثبيت، يُحسب الطلب من حصة المتجر في الدقيقة. هذه الحصة مشتركة بين كل المفاتيح وكل التطبيقات في المتجر، بما فيها مفاتيح `API` الخاصة بالتاجر نفسه. تحصل رموز تثبيت التطبيقات على حصة خطة `Enterprise`، أي 600 طلب في الدقيقة، مهما كانت خطة المتجر، إلا إذا حدّدت `DZBuild` حدًا آخر لذلك المتجر.

تطبّق البوابة `https://api.dzbuild.app` أيضًا سقفًا قدره 600 طلب في الدقيقة لكل متجر قبل أن يصل الطلب إلى خوادم `DZBuild`. ولا تأخذ بالحد الآخر الذي تحدّده `DZBuild` لمتجر ما، فيبقى ذلك المتجر محدودًا بـ 600 عندها.

لبعض نقاط الوصول المكلفة حصة إضافية لكل متجر فوق هاتين الحصتين:

| نقاط الوصول                                                          | الحد لكل متجر                   |
| -------------------------------------------------------------------- | ------------------------------- |
| رفع صورة منتج                                                        | 10 في الدقيقة، و3 في الوقت نفسه |
| الإرسال إلى شركة التوصيل، ربط شركة التوصيل واختبارها ومزامنة أسعارها | 6 في الدقيقة، و2 في الوقت نفسه  |
| كتابات أقسام الصفحة الرئيسية                                         | 30 في الدقيقة، و5 في الوقت نفسه |

## 429 Too Many Requests[​](#429-too-many-requests "رابط مباشر إلى 429 Too Many Requests")

عندما تمتلئ حصة، تجيب الواجهة البرمجية بـ `429`:

```
{

  "error": {

    "code": "rate_limited",

    "message": "Per-minute API limit exceeded for this app install",

    "retry_after": 23

  },

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

}
```

يحمل الرد أيضًا ترويسة `Retry-After` بنفس عدد الثواني. تبيّن الرسالة أي حصة امتلأت: `Per-minute API limit exceeded for this app install` لحصتك، و`Per-minute API limit exceeded for this store` لحصة المتجر. أما رفض البوابة نفسها لسقف المتجر فنصّه `Per-minute API limit exceeded for this key`. انتظر `retry_after` ثانية، ثم أعد إرسال الطلب بنفس قيمة `Idempotency-Key`.

إذا جرت عمليات مكلفة كثيرة في الوقت نفسه، يكون الرد `429` مع رمز الخطأ `too_many_concurrent` وقيمة `retry_after` تساوي 5 ثوانٍ.

## 402 Payment Required[​](#402-payment-required "رابط مباشر إلى 402 Payment Required")

يعني الرد `402` أن الطلب لن يمرّ حتى يدفع التاجر مقابل شيء ما. إعادة المحاولة لا تفيد. اعرض على التاجر ما عليه فعله.

| رمز الخطأ        | المعنى                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `no_credit`      | رصيد `WhatsApp` للمتجر فارغ (راجع [واجهة WhatsApp](https://dzbuild.dev/ar/ar/whatsapp.md)). يشحنه التاجر من لوحة التحكم. |
| `quota_exceeded` | بلغ المتجر حصة شهرية من الطلبات حدّدتها له `DZBuild`.                                                                    |

## Idempotency-Key[​](#idempotency-key "رابط مباشر إلى Idempotency-Key")

يجب أن تحمل طلبات `POST` و`PATCH` و`DELETE` ترويسة `Idempotency-Key`. ولا تحتاجها طلبات `GET` و`PUT`.

```
POST /v1/orders HTTP/1.1

Host: api.dzbuild.app

Authorization: Bearer dzpk_live_xxxxxxxx

Idempotency-Key: create-order-7f3a9c21

Content-Type: application/json
```

القواعد كما تطبّقها الواجهة البرمجية:

* المفتاح 64 حرفًا على الأكثر من بين `A-Z` و`a-z` و`0-9` و`_` و`-` و`:` و`.`. المفتاح الغائب أو غير الصالح يُجاب بـ `400` مع رمز الخطأ `bad_request`.
* المفتاح تابع لرمز تثبيت واحد. مفاتيح تثبيتين مختلفين لا تتصادم أبدًا.
* تحفظ `DZBuild` الرد مدة 24 ساعة. إرسال المفتاح نفسه بنفس الطريقة والمسار والجسم يُرجع الحالة والجسم المحفوظين دون تنفيذ الطلب من جديد، مع الترويسة `Idempotency-Replay: 1`.
* استعمال المفتاح نفسه بطريقة أو مسار أو جسم مختلف يُجاب بـ `422` مع رمز الخطأ `idempotency_key_reuse`. سلسلة الاستعلام لا تدخل في المقارنة.
* ردود `4xx` تُحفظ أيضًا. إذا فشل طلب بـ `4xx` وصحّحت الجسم، فأرسله بمفتاح جديد.
* ردود `5xx` و`429` لا تُحفظ، فإعادة المحاولة بالمفتاح نفسه تنفّذ الطلب من جديد.
* يُحفظ الرد عند انتهاء الطلب الأول. طلبان يُرسلان في اللحظة نفسها بالمفتاح نفسه قد يُنفَّذان كلاهما، فلا ترسل محاولات متوازية.

أنشئ مفتاحًا واحدًا لكل عملية، انطلاقًا من معرّف المهمة لديك مثلًا، وأعد استعماله في كل إعادة محاولة لتلك العملية.