IOSOR

IOSOR Kennis

Idempotentie van de send-API: duplicaten, retries en geld

Ontwikkelaarsgids voor prepaid send-API’s — idempotentiesleutels, veilige retries, duplicaatpreventie en ledger-vriendelijke correlatie, zodat engineeringfouten geen financiële incidenten worden.

Timeouts gebeuren. Load balancers retried. Mobiele clients double-tappen. Zonder idempotentie wordt "één keer versturen" een dubbele prepaid-debit met dubbele OTP-UX. Deze gids is voor engineering en technisch product die een white-label prepaid messaging-API integreren — waar elk duplicaat zichtbaar is in de wallet. IOSOR verwacht money-aware integraties: geauthenticeerde calls, correleerbare debits en clientfouten die nooit vreemde merk-payloads dumpen.

Waarom duplicaten geldproblemen worden

Faalmodus Gebruiker ziet Wallet ziet
Client-timeout + blinde retry Twee OTP's / twee alerts Twee debits
Niet-idempotente webhook-handler Dubbele side effects Verwarring bij success
Gebruikers-resend gestapeld op auto-retry Geïrriteerde gebruikers Opgehoopte units
Geen correlatie "Het faalde"-tickets Ongepaarde ledgerregels

Demo's vergeven dit. Productie-finance niet.

Idempotentiesleutels die retries overleven

Een serieuze send-path accepteert een client-gegenereerde sleutel die uniek is per business-intent, niet per TCP-poging. Deze moet bij replay binnen een duidelijk TTL-venster hetzelfde accepted result teruggeven. Dit voorkomt dat er stil een tweede debit voor dezelfde intent wordt aangemaakt. De sleutel moet worden gelogd naast message-ID en prepaid-referentie. Hij moet werken over timeouts, gateway-retries en support-redrives.

Retry-budgetten vs gebruikers-resend

Automatische retries hebben een budget nodig: max pogingen, backoff en welke foutklassen retrybaar zijn. Door de gebruiker gestarte resend is een andere productactie met eigen limieten en kosten. Het mengen van beide maakt van een instabiel netwerk een financieel event. Koppel beide aan stop-bij-laag-saldo en duidelijke afwijzingsredenen zodat product en finance één waarheid delen.

Checklist voor koper / engineering

  1. Gedocumenteerde idempotentiesleutel-semantiek en TTL.
  2. Replay-test die één debit per intent bewijst.
  3. Auto-retry-budget gescheiden van gebruikers-resend-logica.
  4. Correlatie-ID's over request, berichtstatus en prepaid-ledger.
  5. Staging die echte corridors oefent — mock-green-lights zijn geen lanceringen.
  6. Sleutelhygiëne en least-privilege voor send-credentials.
  7. Afhandeling van 429- en 503-codes zonder verlies van de originele intent-sleutel.
  8. Geautomatiseerde alerts voor hoge afwijzingspercentages van duplicaatsleutels.

Rode vlaggen

  • "Gewoon retryen tot 200" zonder idempotentiesleutels.
  • Webhook-handlers die niet idempotent zijn en side effects dubbel triggeren.
  • Volledige secret keys of auth-tokens in logs of support-tickets.
  • Fouten die payloads van externe merken of interne stack-traces aan gebruikers tonen.
  • Geen monitoring op sleutelafwijzingen.

Begin met IOSOR

In de verzendconsole vuurt u één OTP of alert af met een door de client gegenereerde idempotentiesleutel. Forceer een clienttimeout en speel hetzelfde verzoek binnen de sleutel-TTL opnieuw. Open het prepaid-ledger: die intentie moet één debit en één zichtbaar bericht tonen. Twee rijen betekent dat de sleutel de retry niet overleefde — herstel TTL en handler voordat de corridor Live blijft.

IOSOR takeaway

Doe: behandel elke send eerst als ledgerevent. De sleutel is uniek per bedrijfsintentie, niet per TCP-poging. Auto-retry heeft een budget; de gebruikerstik op opnieuw verzenden is een andere productactie met eigen prepaidkosten.

Niet doen: hameren tot 200 zonder sleutel, of een niet-idempotente webhook een tweede bijeffect laten slaan. Twee OTP’s voor één tik is een geldbug, geen netwerkverhaal.

Was deze gids nuttig?

Gerelateerde gidsen