كل طلبات POST و PATCH و DELETE تتطلب رأس Idempotency-Key.

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

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

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

أما على الاسم البديل الداخلي dzbuild.com/api/v1 فيُتحقَّق من الرأس لكن لا تُملأ أي ذاكرة إعادة تشغيل — وطلبان متطابقان من نوع POST /v1/orders بالمفتاح نفسه يُنشئان طلبيتين. سبب إضافي للتكامل مع api.dzbuild.app وحده.

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

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

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

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

نطابق على المفتاح وحده — ولا نقارن الحمولات إطلاقًا. إعادة استخدام مفتاح مع محتوى مختلف تعيد الاستجابة الأولى بدل إرجاع خطأ، بصمت، ولمدة 24 ساعة. لذا ولّد مفتاحًا واحدًا لكل عملية منطقية (UUID جديد)، لا مفتاحًا لكل نقطة نهاية أو لكل جلسة أو لكل يوم.

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

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

ولا تخلط بينه وبين X-Cache: HIT|MISS، فهو إشارة منفصلة خاصة بطلبات GET وحدها، صادرة عن ذاكرة القراءة المؤقتة.