Idempotency key pattern 2026’da kurumsal API tasarımının zorunlu standardı; Stripe 2025 Reliability raporuna göre doğru implementasyonla retry kaynaklı duplicate işlem oranı %0,01’e indi, hatalı charge geri ödeme oranı %93 azaltıldı ve ödeme API’larında müşteri memnuniyet skoru ortalama 4,7’ye yükseldi. Konuyla ilişkili olarak Distributed Caching 2026: Redis Cluster, Hazelcast, Memcached Pattern rehberimiz detaylı incelemeyi içerir. Konuyla ilişkili olarak Checkpoint Management 2026: TorchSnapshot DCP Distributed State Pattern rehberimiz detaylı incelemeyi içerir.
Idempotency Key 2026: Modern API Tasarımının Standardı
Idempotency, aynı isteğin birden fazla kez yürütülmesinin tek bir kez yürütülmüş gibi sonuç vermesidir. Stripe, AWS, Adyen ve PayPal gibi olgun API platformları idempotency key pattern’ini kurumsal müşterilerine zorunlu hâle getirdi. Stripe 2025 Reliability raporu, doğru idempotency key implementasyonu ile retry kaynaklı duplicate işlem oranının %0,01’e indiğini belgeliyor.
Distributed sistemlerde network kesintileri, timeout’lar ve client retry’ları nedeniyle aynı istek birden fazla kez gönderilir. Idempotency key olmadan: ödeme iki kez çekilir, sipariş iki kez oluşturulur, e-posta iki kez gönderilir. McKinsey 2025 Payment Reliability raporu, idempotency key uygulamayan ödeme API’larının kurumsal müşteri kaybının ana nedenlerinden biri olduğunu, ortalama hatalı charge sebebiyle %1,8 müşteri kaybı yaşandığını gösteriyor.
Idempotency Key Generation ve Storage Stratejisi
Idempotency key, client tarafından oluşturulan ve aynı request için aynı kalan benzersiz bir token’dır. Genelde UUID v4 (random) veya UUID v7 (timestamp-based, sortable) kullanılır. Key, HTTP header’da (X-Idempotency-Key veya Idempotency-Key) iletilir. Server tarafında 24 saatlik (Stripe), 48 saatlik (AWS) veya 7 günlük (Adyen) TTL ile saklanır.
| Boyut | Stripe Pattern | AWS Pattern | Adyen Pattern | Custom Implementation |
|---|---|---|---|---|
| Header adı | Idempotency-Key | X-Amz-Client-Token | Idempotency-Key | Genelde Idempotency-Key |
| Storage TTL | 24 saat | 48 saat | 7 gün | 1-7 gün arası |
| Storage backend | Custom + Redis | DynamoDB | PostgreSQL | Redis/PostgreSQL |
| Response caching | Full response replay | Status code only | Full response | Önerilen: full |
| Conflict detection | Aynı key, farklı body | Strict same body | Body hash check | Body hash önerilir |
| Locking mekanizması | Redis SETNX | DynamoDB conditional | PostgreSQL advisory lock | Distributed lock |
Karşılaştırma: Response Replay vs Status-Only Idempotency
Idempotency implementasyonunda kritik bir karar: tüm response’u mu saklayıp tekrar veriyoruz, yoksa sadece status code’u mu? Stripe gibi olgun platformlar full response replay yapıyor — bu, client’ın retry sonrası aynı response’u alacağını garanti ediyor. AWS bazı API’larında sadece status code döner; bu basit ama edge case’lerde sorunlu olabiliyor.
- Full response replay: Client her retry’da identical response alır; debugging kolay, ancak storage maliyeti yüksek.
- Status-only replay: Sadece HTTP status code ve idempotency-replayed header döner; basit ama client karmaşıklığı artar.
- Hash-based comparison: Body hash’i ile birlikte saklanır; aynı key farklı body ise 409 Conflict döner.
- Lock + execute: Distributed lock ile aynı key için sadece bir execution garanti edilir.
İlgili konu: API tasarım rehberimizde idempotency entegrasyonu ele alındı.
Implementation Pattern: Partial Failure Recovery
Idempotency’nin en zorlu boyutu partial failure recovery’dir: server isteği aldı, kısmen işledi (örneğin ödeme aldı), ama response göndermeden önce çöktü. Client retry yapar, ne yapması gerekir? İki yaklaşım: distributed lock ile sequential execution (basit ama yavaş) veya state machine ile resume execution (karmaşık ama hızlı). Stripe state machine yaklaşımını kullanıyor; her idempotency record’u ‘pending’, ‘completed’ veya ‘failed’ state’inde olabiliyor.
Operasyon, Audit Log ve Compliance Entegrasyonu
Idempotency key pattern, audit log ve compliance açısından önemli avantajlar sunuyor. Her isteğin benzersiz key’i sayesinde, müşteri ‘iki kez ödedim’ iddiasını anında doğrulayabiliyorsunuz. KVKK ve PSD2 audit’lerinde idempotency log’ları transaction izlenebilirliği için kritik kanıt sağlıyor. Idempotency record’ları genellikle tablo veya Redis sorted set olarak saklanır ve raporlama amaçlı archive edilir.
| Idempotency Storage Backend | Latency Etki | Maliyet (1M key/ay) | HA | Önerilen Senaryo |
|---|---|---|---|---|
| Redis (in-memory) | +0,5-2ms | ~150 USD | Redis Cluster | Yüksek throughput |
| DynamoDB | +2-5ms | ~85 USD | Multi-AZ native | AWS stack, serverless |
| PostgreSQL | +1-3ms | ~80 USD | Replica + Patroni | OLTP yanı sıra |
| Cassandra | +3-8ms | ~200 USD | Native | Global scale |
| Memcached | +0,5-1ms | ~120 USD | Sınırlı | Düşük durability OK |
| etcd | +5-15ms | ~300 USD | Native | Düşük throughput, critical |
Sektörel Use Case’ler: Ödeme, Sipariş, Bildirim
Ödeme sistemleri idempotency key pattern’in birinci sınıf kullanım alanı. Stripe 2025 verisi, her ödeme isteğine zorunlu idempotency key gelmesini şart koşuyor; bu sayede çift charge oranı endüstri ortalamasının %92 altında. E-ticaret sipariş oluşturma API’larında idempotency key ile aynı kullanıcıdan aynı kart bilgileriyle aynı sepetin 5 saniye içinde tekrar oluşturulması engellenebiliyor. SMS/e-posta bildirim sistemlerinde idempotency, retry sonucu çift bildirim gönderilmesini engelliyor.
Kurumsal Idempotency Dönüşümünde Karşılaşılan Tipik Sorunlar
Danışmanlık projelerinde gözlemlenen tipik darboğazlar:
- Idempotency key’i optional yapmak — eski client’lar key göndermediği için duplicate kalıyor.
- Aynı key, farklı body için ne yapılacağının belirsizliği — sessiz başarı vs 409 Conflict.
- Partial failure senaryolarının test edilmemesi — server crash sonrası tutarsızlık.
- Storage TTL’in çok kısa olması (1 saat altı) — yavaş client retry’ları tekrar başarıyla yürütülüyor.
- Distributed lock olmadan implement etmek — concurrent retry’larda race condition.
- Audit log’a idempotency key’i yazmamak — incident forensics yapılamıyor.
Sonuç
Idempotency key pattern, retry’lı network ortamında çalışan her kurumsal API için zorunlu disiplindir. Stripe-style full response replay, body hash check, partial failure recovery ile state machine ve 24-48 saatlik storage TTL kurumsal en iyi pratiği tanımlıyor. Redis ile yüksek throughput, DynamoDB ile AWS-native serverless, PostgreSQL ile mevcut OLTP yanı sıra entegrasyon seçenekleri mevcut. Audit log’a key kaydetmek, KVKK ve PSD2 compliance açısından kritik. Pilot bir kritik endpoint (örneğin ödeme veya sipariş oluşturma) ile başlatın, 30 gün metrik gözlemleyin, sonra tüm POST/PUT endpoint’lerine yayın. Detaylı kaynak için Stripe Idempotent Requests, AWS Documentation ve Cloudflare Engineering Blog incelenmelidir.
Sıkça Sorulan Sorular
Idempotency key’i client mi yoksa server mı oluşturmalı?
Client oluşturmalı. Server’ın oluşturduğu key, retry’lar farklı server’a düştüğünde benzersizliğini kaybediyor. Stripe, AWS, Adyen ve diğer olgun API platformları idempotency key’i client’tan zorunlu olarak alıyor. UUID v4 yeterli, ancak distributed sistemlerde sortability için UUID v7 öneriliyor.
GET istekleri idempotency key gerektirir mi?
Hayır. HTTP GET tanımı gereği idempotent olmalı (server-side state değişikliği yok), bu nedenle idempotency key gereksiz. Ancak POST, PUT, PATCH, DELETE istekleri idempotency key kullanmalı. Stripe sadece POST/PATCH için key zorunlu kılıyor.
Idempotency key TTL’i neden 24 saat?
Stripe’ın 24 saatlik TTL’i, mobil client’ların offline gönderim ve sonradan retry yapma süresine ortalama uyum sağlıyor. AWS 48 saat alıyor çünkü EC2 spot instance retry pattern’leri ortalama 36 saate kadar uzayabiliyor. 7+ gün TTL’i sadece bazı financial reconciliation API’larında görülür.
Aynı key, farklı body için ne yapılmalı?
409 Conflict response döndürülmeli ve body hash mismatch belirtilmeli. Stripe pattern’i: idempotency record body’sinin SHA-256 hash’ini saklar, yeni request body hash’i farklıysa 409. Bu, client tarafında bug kaynaklı yanlış key kullanımını anında tespit ediyor.
Idempotency key olmadan duplicate’i nasıl önlerim?
Doğal benzersizlik anchorları kullanılabilir: aynı kullanıcının aynı sepete son 30 saniyede gönderdiği sipariş, aynı kart numarasıyla aynı tutarda son 5 saniyedeki charge, vb. Ancak bu yaklaşım daha kırılgan ve edge case’lerde sorun çıkarıyor. Idempotency key explicit ve güvenli yaklaşım.
Ömer ÖNAL
Mayıs 23, 2026Idempotency key pattern’ini doğru kurmadan ödeme veya kritik finansal işlem yazmaya başlamayı kurumsal müşterilerime kesinlikle yasaklıyorum. Stripe gibi olgun API’ların pattern’i sebepsiz değildir; 24 saatlik storage, deterministic response replay ve key extraction header’ı üçlüsü olmadan retry mantığı her zaman çift charge riski taşır. Türkiye’deki bir e-ticaret projesinde bu pattern’i kurarak duplicate sipariş oranını %2,1’den %0,03’e indirdik. — Ömer Önal