Bir İade API'sinde İdempotency ve Yeniden Deneme (Retry)

Bir müşterinin iadesi onaylanır, iade ödemesi tetiklenir ve onay sayfası takılır. Destek kutunuz 'iademe ne oldu?' mesajlarıyla dolar, biri butona tekrar basar ve finans ekibi aynı siparişte iki ayrı iade kaydı olduğunu fark eder. Bu varsayımsal bir uç durum değildir — iade mühendisliğinde en sık görülen üretim kesintilerinden biridir ve tam olarak şu yüzden yaşanır: bir ağ zaman aşımı, karşı taraftaki işlemin gerçekten tamamlanıp tamamlanmadığı konusunda size hiçbir şey söylemez.

Yeniden denemeler (retry) kaçınılmazdır. Mobil ağlar kopar, yük dengeleyiciler zaman aşımına uğrar, ağ geçitleri hız sınırı uygular ve istemciler (haklı olarak) dayanıklı kalmak için başarısız istekleri yeniden dener. Sorun retry'ların olması değil — çoğu iade API'sinin ve bunun üzerine kurulu mağaza entegrasyonlarının retry'ları güvenli hale getirecek şekilde tasarlanmamış olmasıdır. Eğer iade API entegrasyonunuz gelen her iade talebini, tekrarlanmış olma ihtimali olan bir talep yerine tamamen yeni bir talimat gibi ele alıyorsa, çift iade er ya da geç kaçınılmaz olur.

Ağ üzerinde 'tam olarak bir kez' diye bir şey yoktur

Dağıtık sistemler teorisi bu konuda nettir: güvenilmez bir ağ üzerinden 'en az bir kez' teslimat veya 'en çok bir kez' teslimat inşa edebilirsiniz, ancak her iki tarafın da işbirliği yapmadığı sürece gerçek 'tam olarak bir kez' çalıştırma mümkün değildir. Tam bu hata modunu ele alan bir ödeme mühendisliği rehberi bunu açıkça ortaya koyar — idempotent olmayan ödeme işlemleri, üretim sistemlerinde çift tahsilat ve çift iadenin başlıca nedenidir, çünkü hiçbir yanıt almayan bir istemci, 'sunucu talebimi hiç almadı' ile 'sunucu talebi işledi ama yanıt kayboldu' arasında ayrım yapamaz. Bu tam olarak ödemeler bağlamında ele alınan konu için kanonik kaynak olarak Stripe'ın idempotency dokümantasyonuna bakabilirsiniz; bu, bir iade platformunda iade işlemine birebir uyar.

Özellikle bir iade akışında, retry'ı tetikleyen zaman aşımı genellikle üç noktadan birinde yaşanır: mağazanın önyüzünün iadeyi onaylamak için iade API'sini çağırması, iade API'sinin iade ödemesini gerçekleştirmek için ödeme işlemcisini çağırması ya da iade platformundan mağazanın sipariş yönetim sistemine giden bir webhook teslimatı. Bu adımların her birinin kendi idempotency sözleşmesine ihtiyacı vardır — tüm zinciri tek bir kara kutu gibi ele almak, tek tek servisler izole halde 'sorunsuz görünse' bile çift iadelerin sızmasına neden olur.

İdempotency anahtarları: gerçekten işe yarayan mekanizma

İdempotency anahtarı, çağıran taraf tarafından üretilen ve değişiklik yapan bir isteğe (iade oluşturma, iade onaylama, mağaza kredisi verme) eklenen benzersiz bir jetondur. Sunucu, bu anahtarı ilk başarılı çalıştırmanın sonucuyla birlikte saklar. Aynı anahtar tekrar gelirse — çünkü istemci bir zaman aşımından sonra retry yapmıştır — sunucu işlemi yeniden çalıştırmaz. Bunun yerine ilk çağrının saklanmış sonucunu döndürür. İstemci her iki durumda da cevabını alır; altta yatan iade ise yalnızca bir kez gerçekleşir.

Bir iade platformunu değerlendirirken mağazaların gözden kaçırdığı kritik detay, anahtarı kimin ürettiğidir. Bu, sunucu değil, istemci olmalıdır — önyüz, uygulama ya da iadeyi başlatan sistem. Anahtarı sunucu üretirse, kaybolan bir yanıttan sonra yapılan retry basitçe yeni bir anahtar alır ve koruma tamamen işlevsiz kalır. Bu yüzden idempotency, yalnızca eşzamanlı istek yolunun değil, iade API webhook'larının da birinci sınıf bir parçası olmalıdır: webhook teslimatı tasarım gereği yeniden denenir ve mağazanın sipariş sisteminin alıcı tarafta da aynı çift-önleme mantığına ihtiyacı vardır.

Bir retry yeni bir talimat değildir. İlk seferde cevap kaybolduğu için iki kez sorulan aynı talimattır. Bunu her katmanda böyle ele alın, yoksa dördüncü katman diğer üçünü boşa çıkarır.

İdempotency anahtarının ötesinde güvenli retry desenleri

İdempotency anahtarları, tekrar eden çalıştırma sorununu çözer. Ancak istemcinin ne zaman ve nasıl retry yapması gerektiğini tek başına çözmez. İyi tasarlanmış bir iade entegrasyonu, bunun üzerine birkaç ek desen daha ekler:

• Jitter'lı üstel geri çekilme (exponential backoff) — retry'ları aralıklandırmak (1sn, 2sn, 4sn, rastgele jitter ile) bir kesintiden yeni toparlanan iade API'sinin retry fırtınasıyla boğulmasını önler.
• Açık retry-güvenli durum kodları — 200 veya 201 retry yapma anlamına gelir; bir 5xx veya ağ zaman aşımı retry'ın güvenli olduğu anlamına gelir; bir 4xx (429 hariç) isteği düzeltmeniz gerektiği, körlemesine retry yapmamanız gerektiği anlamına gelir.
• Yalnızca istek değil, kaynak üzerinde durum makinesi — bir iade kaydının tanımlı bir durumu olmalı (talep edildi, onaylandı, iade bekliyor, iade edildi, başarısız) ki tamamen bağımsız gelen tekrar bir istek bile, kaynak zaten bir uç durumda olduğu için reddedilebilsin.
• Keyfi bir TTL yerine iş mantığına bağlı idempotency anahtarı süresi — bir iade anahtarı, bazı ekiplerin varsayılan olarak kullandığı 5 dakikalık önbellek yerine, makul bir istemci retry penceresi kadar, genellikle 24 ila 72 saat yaşamalıdır.
• Webhook retry'ları için dead-letter kuyrukları — N başarısız teslimat denemesinden sonra olayı sonsuza kadar yeniden denemek veya sessizce düşürmek yerine manuel inceleme için ayırın.

Finans koltuğundan bakıldığında bu nasıl görünür

Perakende ve e-ticaret finans ekipleri API katmanını nadiren görür — onlar mutabakat raporunu görür. Çift iadeler orada, işlenen iadeler ile verilen iadeler arasında açıklanamayan bir fark olarak ortaya çıkar ve sonradan izlemesi pahalıdır çünkü finans ekibi fark ettiğinde, buna neden olan retry olayı haftalar öncesinin loglarında gömülü kalmıştır. İade hacmi üzerine sektör verileri ölçeği gösteriyor: National Retail Federation, yalnızca işlenen değer bazında ABD perakendecilerine iadelerin yıllık yüz milyarlarca dolara mal olduğunu tahmin ediyor — bu hacme karşı yüzde birin küçük bir kesri kadar bile bir çift-iade oranı, tamamen denetim katmanı yerine mühendislik katmanında önlenebilecek maddi bir kalemdir.

Bu aynı zamanda salt doğruluk değil, bir hız sınırı ve kapasite meselesidir de. İdempotency eksik olduğunda, retry'lar gerçek yükü katlar: takılan tek bir istek, API'ye art arda gelen üç dört tekrar denemeye dönüşebilir; bu da kötü ayarlanmış bir throttle'ı tetiklemenin en hızlı yollarından biridir. İade API hız sınırlarınızı retry stratejinizle birlikte anlamak önemlidir, çünkü eksik idempotency desteğinin tetiklediği bir retry fırtınası kendisi de 429 hatalarına yol açabilir, bu da daha fazla retry'ı tetikler — bu geri besleme döngüsü, yoğun satış hafta sonlarında birden fazla iade entegrasyonunu çökertmiştir.

Bir iade API'sinin idempotency desteğini değerlendirmek için pratik kontrol listesi

1. 1API, her değişiklik yapan uç noktada (onaylama, iade, mağaza kredisi verme) istemci tarafından sağlanan bir idempotency anahtarını kabul ediyor mu?
2. 2Anahtar doğru kapsamlanmış mı — iki farklı mağaza ya da iki farklı iade yanlışlıkla aynı anahtarda çakışabilir mi?
3. 3API, tekrar eden bir anahtarda ne döndürüyor — orijinal sonucu mu, bir 409 çakışma yanıtı mı yoksa (yanlış şekilde) yeni bir çalıştırma mı?
4. 4İdempotency anahtarları ne kadar süre saklanıyor ve bu pencere belgelenip yapılandırılabilir mi?
5. 5Webhook'lar alıcı tarafta idempotent mi, mağazaların tekrar önleme için kullanabileceği teslimat ID'leriyle birlikte mi geliyor?
6. 6İdempotency anahtarı mekanizmasından bağımsız olarak, zaten uç durumda olan bir iade üzerindeki işlemleri reddeden kaynak seviyesinde bir durum makinesi var mı?
7. 7Tedarikçi, deneme yanılmaya bırakmak yerine retry rehberliği (geri çekilme aralıkları, hangi durum kodlarının retry için güvenli olduğu) yayınlıyor mu?

Eğer bir tedarikçi teknik değerlendirme sırasında bu soruları net şekilde yanıtlayamıyorsa, entegrasyonunuzda çift iadenin teorik değil, canlı bir risk olduğunu varsayın. Bu tam olarak, ölçek için inşa edilmiş bir iade API'sini yalnızca demoda çalışan birinden ayıran türden bir detaydır.