التكرار الآمن
الشبكات تعيد المحاولة. Idempotency-Key يجعل إعادة الكتابة آمنة: الطلب الثاني بنفس المفتاح يعيد الرد المخزَّن للأول بدل تنفيذ العمل مرتين.
POST /v1/inbound-events
Idempotency-Key: order-44821-msg-3٨–١٢٨ حرفاً من [A-Za-z0-9_.:-]. نطاقه التطبيق. مطلوب على POST /v1/inbound-events واختياري على بقية الكتابات. يُحفظ ٢٤ ساعة.
ماذا يحدث
| الحالة | الرد |
|---|---|
| أول طلب بالمفتاح | يُنفَّذ ويُخزَّن رده |
| نفس المفتاح ونفس الطريقة والمسار والجسم | الرد المخزَّن مع Idempotent-Replayed: true |
| نفس المفتاح وطلب مختلف | 409 idempotency_key_reused |
| نفس المفتاح والأول ما زال يعمل | 409 idempotency_in_progress · Retry-After: 1 |
| الأول انتهى بـ 5xx أو فشل شبكة | لا يُخزَّن شيء؛ الإعادة تُنفَّذ |
«نفس الجسم» يعني بايتات JSON متطابقة: سلسِل مرة واحدة وأعد إرسال البايتات نفسها.
طبقتان للأحداث الواردة
Idempotency-Key يحمي من إعادة نداء HTTP. وexternal_message_id — معرّف الرسالة من قناتك — يجعل الرسالة نفسها حدثاً واحداً إلى الأبد مهما اختلف المفتاح: الإرسال الثاني يجيب 202 مع duplicate: true وevent_id الأصلي.