IOSOR

IOSOR Znalosti

Idempotence send API: duplicity, retry a peníze

Průvodce pro vývojáře prepaid send API — idempotenční klíče, bezpečné retry, ochrana před duplicitami a korelace přátelská ledgeru, aby chyby engineeringu nebyly finančními incidenty.

Timeouty se stávají. Load balancery dělají retry. Mobilní klienti dají double-tap. Bez idempotence se z produktu "odeslat jednou" stane dvojité prepaid stržení a duplicitní OTP UX. Tento průvodce je pro engineering a technický product, kteří integrují white-label prepaid messaging API — kde je každá duplicita vidět v peněžence. IOSOR očekává money-aware integrace: autentizovaná volání, korelovatelné debety a klientské chyby, které nikdy nevypisují cizí brand payloady. Blízko USD 1 000+ měsíčního užití platformy už disciplína duplicit není volitelná.

Proč se z duplicit stávají peněžní problémy

Režim selhání Uživatel vidí Peněženka vidí
Timeout klienta + slepý retry Dvě OTP / dvě upozornění Dva debety
Neidempotentní webhook handler Dvojité side effects Zmatek u success
User resend na auto-retry Naštvaní uživatelé Nahromaděné units
Chybějící korelace Tikety "selhalo" Nesourodé řádky ledgeru

Dema odpustí. Produkční finance ne. Při prepaid intenzitě se z víkendu slepých retry stane reconciliační projekt, ne poznámka pod čarou v logu. Navrhněte happy path i timeout cestu se stejným pravidlem debetu.

Idempotenční klíče, které přežijí retry

Vážná send cesta přijímá klientem generovaný klíč (nebo ekvivalent), který je unikátní na business intent, nikoliv na TCP pokus. Musí vrátit stejný accepted výsledek při replay v jasném TTL okně. Tím zabráníte tichému vytvoření druhého debetu pro stejný intent. Klíč logujte vedle message ID a prepaid reference. Musí fungovat přes timeouty, gateway retry a support redrive.

Rozpočty retry vs opětovné odeslání uživatelem

Automatické retry potřebují rozpočet: max pokusů, backoff a které třídy chyb jsou retryable. User-initiated resend je jiná produktová akce s vlastními limity a prepaid nákladem. Smíchání z nestabilní sítě udělá víkendovou událost peněženky. Spárujte obojí se stop-on-low-balance a jasnými důvody zamítnutí, aby product a finance sdíleli jednu pravdu.

Checklist kupujícího / engineeringu

  1. Dokumentovaná sémantika idempotenčního klíče a TTL.
  2. Replay test, který dokazuje jeden debet pro jeden intent.
  3. Oddělený rozpočet auto-retry od logiky user resend.
  4. Korelační ID napříč requestem, stavem zprávy a prepaid ledgerem.
  5. Staging, který cvičí reálné koridory — mock zelená světla nejsou launch.
  6. Hygiena klíčů a least privilege pro send credentials.
  7. Ošetření 429 a 503 kódů bez ztráty původního intent klíče.
  8. Automatizované alerty pro vysokou míru zamítnutí duplicitních klíčů.

Červené vlajky

  • "Jen retry do 200" bez použití idempotenčních klíčů.
  • Webhook handlery, které nejsou idempotentní a spouštějí side effects dvakrát.
  • Plné secret klíče nebo auth tokeny v logách či tiketech.
  • Chyby vkládající upstream brand payloady nebo interní stack trace koncovým uživatelům.
  • Absence limitů na retry.

Začněte s IOSOR

V odesílací konzoli spusťte jeden OTP nebo alert s klientským klíčem idempotence. Vynuťte timeout klienta a přehrajte stejný požadavek uvnitř TTL klíče. Otevřete prepaid ledger: ten záměr musí ukázat jeden debet a jednu viditelnou zprávu. Dva řádky znamenají, že klíč nepřežil retry — opravte TTL a handler, než koridor zůstane Live.

Shrnutí IOSOR

Dělejte: berte každý send nejdřív jako událost ledgeru. Klíč je unikátní na obchodní záměr, ne na TCP pokus. Auto-retry má rozpočet; klepnutí uživatele na znovuodeslání je jiná produktová akce s vlastní prepaid cenou.

Nedělejte: mlátit do 200 bez klíče ani nechat neidempotentní webhook razit druhý vedlejší efekt. Dva OTP na jedno klepnutí jsou peněžní chyba, ne síťový příběh.

Byl tento průvodce užitečný?

Související průvodci