IOSOR

IOSOR Rehber

Gönderim API’sinde idempotency: kopyalar, retry ve para

Ön ödemeli gönderim API’leri için geliştirici rehberi — idempotency anahtarları, güvenli retry, kopya engeli ve ledger dostu korelasyon; mühendislik hataları finans olayına dönüşmesin.

Timeout'lar olur. Yük dengeleyiciler retry yapar. Mobil istemciler çift dokunur. Idempotency olmadan "bir kez gönder" ürünü çift ön ödemeli borç ve yinelenen OTP UX'e dönüşür. Bu rehber, white-label ön ödemeli mesajlaşma API'sini entegre eden engineering ve teknik ürün ekipleri içindir — her kopya cüzdanda görünür. IOSOR para bilinci olan entegrasyon bekler: kimlik doğrulamalı çağrılar, eşleştirilebilir borçlar ve yabancı marka yüklerini dökmeyen istemci hataları.

Kopyalar neden para sorununa dönüşür

Arıza modu Kullanıcı görür Cüzdan görür
İstemci timeout + kör retry İki OTP / iki uyarı İki borç
Idempotent olmayan webhook işleyici Çift yan etki Başarıda karışıklık
Otomatik retry üzerine kullanıcı yeniden gönderimi Sinirli kullanıcılar Biriken birimler
Korelasyon yok "Başarısız" ticket'ları Eşleşmeyen ledger satırları

Demolar affeder. Üretim finansı etmez.

Retry’ye dayanan idempotency anahtarları

Ciddi bir gönderim yolu, istemci üretimi anahtar kabul eder ve bu anahtar TCP denemesi başına değil, iş niyeti başına benzersizdir. Net bir TTL penceresinde replay'de aynı kabul sonucunu dönmelidir. Bu, aynı niyet için sessizce ikinci borç oluşturulmasını engeller. Anahtar, mesaj ID'si ve ön ödemeli referansın yanında loglanmalıdır. Timeout, gateway retry ve destek redrive'larında çalışmalıdır.

Retry bütçeleri vs kullanıcı yeniden gönderimi

Otomatik retry'lerin bir bütçeye ihtiyacı vardır: max deneme, backoff ve hangi hata sınıflarının yenilenebilir olduğu. Kullanıcı başlatımlı yeniden gönderim, kendi limitleri ve maliyetleri olan ayrı bir ürün eylemidir. İkisini karıştırmak, kararsız bir ağı finansal bir olaya dönüştürür. Her ikisini de düşük bakiye durdurma ve net ret nedenleriyle eşleştirin ki ürün ve finans tek bir gerçeği paylaşsın.

Alıcı / engineering kontrol listesi

  1. Belgelenmiş idempotency anahtar semantiği ve TTL.
  2. Bir niyet için bir borcu kanıtlayan replay testi.
  3. Kullanıcı yeniden gönderim mantığından ayrılmış otomatik retry bütçesi.
  4. İstek, mesaj durumu ve ön ödemeli ledger arasında korelasyon ID'leri.
  5. Gerçek koridorları çalıştıran staging — sahte yeşil ışıklar lansman değildir.
  6. Gönderim kimlik bilgileri için anahtar hijyeni ve en az yetki.
  7. Orijinal niyet anahtarını kaybetmeden 429 ve 503 kodlarının yönetimi.
  8. Yüksek kopya anahtar ret oranları için otomatik uyarılar.

Kırmızı bayraklar

  • Idempotency anahtarları kullanmadan "200 alana kadar retry yap".
  • Idempotent olmayan ve yan etkileri iki kez tetikleyen webhook işleyicileri.
  • Loglarda veya destek ticket'larında görünen tam gizli anahtarlar veya auth token'ları.
  • Kullanıcılara yabancı marka yüklerini veya iç stack trace'leri yapıştıran hatalar.
  • Anahtar retleri için izleme eksikliği.

IOSOR ile başlayın

Gönderim konsolunda istemci ürettiği eşgüçlülük anahtarıyla bir OTP veya uyarı atın. İstemci zaman aşımı zorlayın, aynı isteği anahtar TTL içinde yeniden oynatın. Prepaid ledger’ı açın: o niyet bir debit ve bir kullanıcıya görünen mesaj göstermelidir. İki satır, anahtarın yeniden denemeyi yaşamadığıdır — koridor Live kalmadan TTL ve işleyiciyi düzeltin.

IOSOR özeti

Yapın: her gönderimi önce ledger olayı sayın. Anahtar iş niyetine özgüdür, TCP denemesine değil. Otomatik yeniden denemenin bütçesi vardır; kullanıcının yeniden gönder tuşu ayrı ürün eylemidir, kendi prepaid maliyetiyle.

Yapmayın: anahtarsız 200’e kadar vurmayın, eşgüçlü olmayan webhook’un ikinci yan etki basmasına izin vermeyin. Bir dokunuşta iki OTP para hatasıdır, ağ hikâyesi değil.

Bu rehber yardımcı oldu mu?

İlgili rehberler