Idempotency

Bir yazma işleminde oluşan ağ hatası, işlemin gerçekleşip gerçekleşmediğini bilmeden sizi ortada bırakır. Birçok kaydı aynı anda değiştiren route’lar bir Idempotency-Key ister; böylece bir yeniden deneme değişikliği iki kez uygulayamaz.

Hangi route’lar bunu gerektirir

Route	Zorunlu
POST /apps/catalog/products/bulk	evet
POST /apps/media/imports	evet
diğer uygulama route’ları	hayır — header yok sayılır

Zorunlu bir anahtarın eksik veya boş olması → 400 idempotency_key_required. 255 karakterden uzun olması → 400. Tüm idempotency reddedişleri hata zarfını kullanır.

Bir anahtar nasıl eşleştirilir

Anahtarlar kurulumunuza özeldir — başka bir uygulama asla sizinkiyle çakışamaz. Bir istek, anahtarı ve METHOD + path + raw body bytes üzerinden hesaplanan bir parmak iziyle tanımlanır. Query string parmak izine dahil değildir ve gövde bayt bayt karşılaştırılır: aynı nesneyi farklı anahtar sırası veya boşluklarla yeniden serileştirmek farklı bir istektir.

Durum	Yanıt
Anahtarın ilk kullanımı	İstek normal şekilde çalışır.
Aynı anahtar, aynı istek, tamamlanmış	Orijinal durum kodu ve gövde, artı Idempotent-Replay: true. Hiçbir şey yeniden çalışmaz.
Aynı anahtar, aynı istek, hâlâ çalışıyor	Retry-After: 1 ile 409 idempotency_in_progress. Aynı anahtarla yeniden deneyin.
Aynı anahtar, farklı istek	422 idempotency_key_reuse. Bir anahtarı yeniden kullandınız — yenisini üretin.
Orijinal yanıt 256 KB’tan büyüktü	409 idempotency_unreplayable: iş yapıldı ve yeniden oynatılamaz. Yeniden denemeyin.
Orijinal istek 5xx ile başarısız oldu	Anahtar serbest bırakılır; yeniden deneme isteği tekrar çalıştırır.

Anahtarlar 24 saat boyunca hatırlanır. Bu süreden sonra aynı anahtar yeni bir istek başlatır.

Anahtar seçimi

Anahtarı denemeden değil, ne yaptığınızdan türetin: her mantıksal işlem için tek bir anahtar, o işlemin her yeniden denemesinde tekrar kullanılır. Referans uygulama zugo:{runId}:{vehicle}:{chunk} kullanır — her senkronizasyon çalıştırması ve her parça için benzersiz, aynı çalıştırma içindeki yeniden denemelerde sabit.