Idempotency

Idempotency-Key write işlemlerinin network timeout veya retry durumlarında yanlışlıkla iki kez uygulanmasını önlemeye yardımcı olur.

Aynı mantıksal operasyon retry ediliyorsa aynı key'i; yeni bir operasyon başlatılıyorsa yeni key'i kullanın.

Problem nedir?

Bir PATCH isteği gönderdiniz ve bağlantı response gelmeden koptu. İşlemin sunucuda uygulanıp uygulanmadığını bilmiyorsunuz.

Aynı isteği rastgele tekrar göndermek bazı write işlemlerinde çift işlem riskine yol açabilir.

Idempotency-Key ne yapar?

Her mantıksal write operasyonuna benzersiz bir key verir. Retry sırasında aynı operasyon aynı key ile tekrar gönderilebilir.

Idempotency-Key: inventory-product-7314-20260831-001

Doğru kullanım

İlk deneme:
Idempotency-Key: stock-update-7314-001

Timeout oldu.

Retry:
Idempotency-Key: stock-update-7314-001

Yeni stok operasyonu:
Idempotency-Key: stock-update-7314-002

Yanlış kullanım

Aynı key'i farklı payload için kullanmak.
Aynı key'i farklı endpoint işlemlerinde kullanmak.
Her retry sırasında yeni key üretmek.
Tamamen yeni bir business işlemi için eski key'i kullanmak.

Kullanıldığı write alanları

Alan	Örnek
Products	Ürün oluşturma/güncelleme
Inventory	Stok güncelleme
Pricing	Fiyat güncelleme
Variant inventory	Varyant stok güncelleme
Variant price	Varyant fiyat güncelleme
Shipping	Tracking güncelleme

Conflict alırsam?

409 response aldıysanız error.code değerini kontrol edin. Aynı key farklı payload ile kullanılmış veya aynı idempotent request halen işleniyor olabilir.

Retry stratejisi

Network timeout veya uygun 5xx durumlarında controlled retry yapabilirsiniz. Aynı mantıksal write request retry ediliyorsa Idempotency-Key değiştirilmemelidir.