IOSOR

IOSOR Vedomosti

Idempotencia send API: duplicity, retry a peniaze

Príručka pre vývojárov prepaid send API — idempotenčné kľúče, bezpečné retry, ochrana pred duplicitami a korelácia priateľská ledgeru, aby chyby engineeringu neboli finančnými incidentmi.

Timeouty sa stávajú. Load balancery robia retry. Mobilní klienti dajú double-tap. Bez idempotencie sa z produktu "odošli raz" stane dvojité prepaid zaťaženie a duplicitné OTP UX. Táto príručka je pre engineering a technický product, ktorí integrujú white-label prepaid messaging API — kde je každá duplicita viditeľná v peňaženke.

IOSOR očakáva money-aware integrácie: autentizované volania, korelovatelné debety a klientské chyby, ktoré nikdy nevyhadzujú cudzie brand payloady. Blízko USD 1 000+ mesačného použitia platformy už disciplína duplicít nie je voliteľná.

Prečo sa z duplicít stávajú peňažné problémy

Režim zlyhania Používateľ vidí Peňaženka vidí
Timeout klienta + slepý retry Dve OTP / dve upozornenia Dva debety
Neidempotentný webhook handler Dvojité side effects Zmätok pri success
User resend na auto-retry Nahnevaní používatelia Nahromadené units
Chýbajúca korelácia Tikety "zlyhalo" Nezosúladené riadky ledgeru

Demá odpustia. Produkčné finance nie. Pri prepaid intenzite sa z víkendu slepých retry stane reconciliačný projekt, nie poznámka pod čiarou v logu. Navrhnite happy path aj timeout cestu s rovnakým pravidlom debetu.

Idempotenčné kľúče, ktoré prežijú retry

Vážna send cesta prijíma klientom generovaný kľúč, ktorý je unikátny na business intent, nie na TCP pokus. Musí vrátiť rovnaký accepted výsledok pri replay v jasnom TTL okne. Tým zabránite tichému vytvoreniu druhého debetu pre ten istý intent. Kľúč logujte vedľa message ID a prepaid referencie.

Rozpočty retry vs opätovné odoslanie používateľom

Automatické retry potrebujú rozpočet: max pokusov, backoff a definíciu retryable chýb. User-initiated resend je iná produktová akcia s vlastnými limitmi a prepaid nákladom. Miešanie týchto dvoch svetov mení nestabilnú sieť na víkendový finančný incident. Spojte oboje so stop-on-low-balance a jasnými dôvodmi odmietnutia.

Checklist kupujúceho / engineeringu

  1. Dokumentovaná sémantika idempotenčného kľúča a TTL.
  2. Replay test, ktorý dokazuje jeden debet na jeden intent.
  3. Oddelený rozpočet pre auto-retry a user resend logiku.
  4. Korelačné ID naprieč requestom, statusom správy a prepaid ledgerom.
  5. Staging, ktorý simuluje reálne koridory — mocky nie sú launch.
  6. Hygiena kľúčov a least privilege pre send credentials.
  7. Spracovanie 429 a 503 kódov bez straty pôvodného intent kľúča.
  8. Automatizované alerty na vysokú mieru zamietnutých duplicitných kľúčov.

Červené vlajky

  • "Retryuj do 200" bez použitia idempotenčných kľúčov.
  • Webhook handlery, ktoré nie sú idempotentné a spúšťajú side effects dvakrát.
  • Full secret kľúče alebo auth tokeny v logoch či support tiketoch.
  • Chyby, ktoré vracajú upstream brand payloady alebo stack trace koncovému používateľovi.
  • Chýbajúce monitorovanie duplicitných kľúčov.

Začnite s IOSOR

V odosielacej konzole spustite jeden OTP alebo upozornenie s klientskym kľúčom idempotencie. Vynúťte timeout klienta a prehrajte rovnakú požiadavku v TTL kľúča. Otvorte prepaid ledger: ten zámer musí ukázať jeden debet a jednu viditeľnú správu. Dva riadky znamenajú, že kľúč neprežil opakovanie — opravte TTL a handler skôr, než koridor ostane Live.

Zhrnutie IOSOR

Robte: berte každý send najprv ako udalosť ledgeru. Kľúč je jedinečný na obchodný zámer, nie na TCP pokus. Auto-retry má rozpočet; ťuknutie používateľa na opätovné odoslanie je iná produktová akcia s vlastnou prepaid cenou.

Nerobte: biť do 200 bez kľúča ani nechať neidempotentný webhook raziť druhý vedľajší účinok. Dva OTP na jedno ťuknutie sú peňažná chyba, nie sieťový príbeh.

Pomohol tento sprievodca?

Súvisiace návody