Idempotency

Ağ takılmaları istemcileri tekrar denemeye iter. Korumasız tekrar denenen gönderim çift push demektir. POST /v1/notifications ve POST /v1/campaigns tekrarları güvenli kılmak için Idempotency-Key başlığı kabul eder.

curl -X POST https://push.example.com/v1/notifications \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: order-48213-shipped" \
  -H "content-type: application/json" \
  -d '{ … }'

Kurallar

Durum	Yanıt
İlk istek	Normal işlenir; durum + gövde 24 saat saklanır.
Aynı anahtar, aynı gövde, 24 saat içinde	Saklanan durum ve gövde, artı Idempotent-Replayed: true başlığı. Hiçbir şey yeniden gönderilmez.
Aynı anahtar, farklı gövde	422 idempotency_key_reused
İlk istek hâlâ işlenirken aynı anahtar	409 idempotency_in_progress — biraz sonra tekrar deneyin
İstek doğrulamada düştü (422)	Anahtar tüketilmez; gövdeyi düzeltip aynı anahtarla tekrar deneyin.
İstek doğrulamadan sonra düştü (5xx)	Talep serbest bırakılır; aynı anahtarla tekrar deneyin.

Anahtarlar uygulama ve uç başına kapsanır — /v1/notifications ve /v1/campaigns'te aynı string iki farklı anahtardır. Niyeti tanımlayan bir şey kullanın: sipariş id'si artı olay adı, iş çalıştırma id'si, ilk denemeden önce ürettiğiniz bir UUID.

Saklama: TTL index'li idempotency koleksiyonu; saklanan gövde istek gövdesinin SHA-256'sına bağlıdır.

Onsuz uçlar

/send, /cancel ve /experiment/winner durum geçişleriyle doğal olarak idempotenttir: zaten sending olan kampanyayı göndermek 409 invalid_state döner, iki kez iptal zararsızdır, ikinci kazanan 409 döner.