كل طلبات POST و PATCH و DELETE تتطلب رأس Idempotency-Key. ويقبل PUT هذا الرأس أيضًا: إذا أرسلت معه مفتاحًا طُبّقت عليه قواعد هذه الصفحة، وإذا أرسلته بلا مفتاح نُفّذ الطلب في كل مرة يصل فيها.

الصيغة: من 1 إلى 64 حرفًا من [A-Za-z0-9_-:.].

استخدم قيمة ثابتة وفريدة لكل عملية منطقية (مثل UUID مولَّد من جانب العميل).

تجري إعادة التشغيل على المنصة نفسها، لذلك يتصرّف https://api.dzbuild.app/v1 والاسم البديل dzbuild.com/api/v1 بالطريقة ذاتها. تُحفَظ الاستجابة لمدة 24 ساعة، وتعود الإعادات مع رأس Idempotency-Replay: 1.

إذا أعدت إرسال POST /v1/orders بالمفتاح نفسه والمحتوى نفسه، تتلقى الاستجابة الأولى ولا تُنشأ طلبية ثانية، أيًّا كان العنوان الذي تستدعيه.

نطاق التخزين المؤقت مرتبط بـkey_id الخاص بك مع قيمة Idempotency-Key: القيمة نفسها المرسلة بمفتاح API مختلف لا تُلغي التكرار.

ولا يزال POST /v1/signups وPOST /v1/events يتطلبان الرأس، غير أنهما يُقبلان بشكل غير متزامن ولا تُخزَّن استجابتهما إطلاقًا، فلا توجد ذاكرة إعادة تشغيل تحمي هذين المسارين.

أما POST /v1/keys وPOST /v1/webhooks فيُرجعان سرًّا لا يظهر إلا مرة واحدة، لذلك لا تُخزَّن استجابتهما هي الأخرى. إعادة المحاولة بالمفتاح نفسه تنفّذ النداء من جديد، وقد تُنشئ مفتاحًا ثانيًا أو webhook ثانيًا. راجع GET /v1/keys أو GET /v1/webhooks قبل أن تعيد محاولة أحدهما.

⚠️ تنبيه — التكرار الآمن يحمي من إعادة المحاولة لا من التسابق

لا تُحفَظ الاستجابة إلا بعد انتهاء الطلب الأول، لذا فطلبان مكرَّران متزامنان فعليًا قد يُنفَّذان كلاهما. رتّب عمليات الكتابة المعرّضة للتكرار تسلسليًا من جانبك.

يرتبط المفتاح بأول طلب استُعمل فيه: طريقته ومساره ومحتواه، أما سلسلة الاستعلام (query string) فلا تدخل في المقارنة. إعادة استخدام مفتاح مع محتوى أو مسار أو طريقة مختلفة تُرجع 422 مع الكود idempotency_key_reuse دون تنفيذ أي شيء. يُقارَن المحتوى بايتًا ببايت، فيجب أن تحمل إعادة المحاولة البايتات نفسها التي أُرسلت في المحاولة الأولى، لا نسخة أعدت بناءها بترتيب مختلف للحقول أو بمسافات مختلفة. ولّد مفتاحًا واحدًا لكل عملية منطقية (UUID جديد)، لا مفتاحًا لكل نقطة نهاية أو لكل جلسة أو لكل يوم.

استجابة 4xx الناتجة عن عملية كتابة تُحفظ وتُعاد لمدة 24 ساعة. بعد تصحيح خطأ في التحقق، أرسل الطلب المصحَّح بمفتاح Idempotency-Key جديد، لأن المفتاح القديم يجيب بـ 422 idempotency_key_reuse على المحتوى المعدَّل. أما حالات الرفض التي تقع قبل وصول طلبك إلى معالجه فلا تُخزَّن إطلاقًا، ومنها 401، وردود 403 المتعلقة بالتسجيل في البرنامج التجريبي أو بالخطة أو بحالة التطبيق، وكل ردود 429، وغياب Idempotency-Key أو خطأ تنسيقه. وردّ 403 بسبب صلاحية ناقصة يصدر عن المعالج نفسه، فيُخزَّن مثل أي 4xx آخر. كذلك استجابات 5xx لا تُخزَّن ويمكن إعادة المحاولة بالمفتاح نفسه. انظر الأخطاء.

اعتمد على الرأس Idempotency-Replay: 1. فالإعادة تعني أنه لم يحدث أي أثر جانبي جديد، وبالتالي تجاوز أي معالجة لاحقة محلية كنت ستنفّذها بعد كتابة حقيقية.

ولا تخلط بينه وبين X-Cache، فهو ترويسة منفصلة خاصة بطلبات GET وحدها وقيمتها دائمًا MISS.