IOSOR

IOSOR Gabay

Idempotency ng Send API: mga duplicate, retry, at pera

Gabay sa developer para sa prepaid send API — mga idempotency key, ligtas na retry, pagpigil sa duplicate, at correlation na madaling i-ledger, para hindi maging financial incident ang engineering error.

May timeout. Nagre-retry ang load balancer. Nagda-double-tap ang mobile client. Kung walang idempotency, ang produktong "isang beses lang magpadala" ay magiging dobleng prepaid debit at duplicate na OTP UX. Gabay ito para sa engineering at technical product na nag-iintegrate ng white-label prepaid messaging API — kung saan bawat duplicate ay kitang-kita sa wallet. Inaasahan ng IOSOR ang money-aware na integration: authenticated na tawag, maikokorelasyon na debit, at client error na hindi naglalabas ng dayuhang brand payload.

Bakit nagiging problema sa pera ang mga duplicate

Failure mode Nakikita ng user Nakikita ng wallet
Client timeout + bulag na retry Dalawang OTP / dalawang alert Dalawang debit
Non-idempotent webhook handler Dobleng side effect Kalituhan sa success
User resend sa ibabaw ng auto-retry Naiinis na user Naipong unit
Walang correlation Ticket na "nabigo" Hindi magkatugmang ledger row

Pinapatawad ng demo. Hindi ng production finance. Sa prepaid intensity, ang weekend ng bulag na retry ay reconciliation project, hindi footnote sa log. Idisenyo ang happy path at timeout path sa iisang debit rule.

Mga idempotency key na nakaligtas sa retry

Ang seryosong send path ay tumatanggap ng client-generated key na unique bawat business intent, hindi bawat TCP attempt. Dapat itong magbalik ng parehong accepted result sa replay sa loob ng malinaw na TTL window. Pinipigilan nito ang tahimik na paglikha ng pangalawang debit para sa parehong intent. Ang key ay dapat naka-log sa tabi ng message ID at prepaid reference. Gumagana ito sa timeout, gateway retry, at support redrive.

Mga budget ng retry vs muling padala ng user

Ang mga automatic retry ay nangangailangan ng budget: max attempts, backoff, at kung anong error classes ang retryable. Ang user-initiated resend ay ibang product action na may sariling rate limits at prepaid cost. Ang paghahalo sa kanila ay kung paano nagiging weekend wallet event ang flaky network. Ipares ang dalawa sa stop-on-low-balance at malinaw na reject reasons para iisang katotohanan ang hawak ng product at finance.

Checklist ng buyer / engineering

  1. Dokumentadong idempotency key semantics at TTL.
  2. Replay test na nagpapatunay ng isang debit para sa isang intent.
  3. Paghiwalay ng auto-retry budget sa user resend logic.
  4. Correlation IDs sa request, message status, at prepaid ledger.
  5. Staging na gumagamit ng totoong corridors — hindi launch ang mock green lights.
  6. Key hygiene at least privilege para sa send credentials.
  7. Paghawak ng 429 at 503 codes nang hindi nawawala ang original intent key.
  8. Automated alerts para sa mataas na duplicate-key rejection rates.

Mga red flag

  • "Just retry until 200" nang walang idempotency keys.
  • Webhook handlers na hindi idempotent at nagti-trigger ng side effects nang dalawang beses.
  • Full secret keys o auth tokens na lumalabas sa logs o support tickets.
  • Errors na nagpapakita ng upstream brand payloads o internal stack traces sa end users.
  • Walang limitasyon sa retry budget.

Magsimula sa IOSOR

Sa send console, magpaputok ng isang OTP o alerto na may idempotency key na gawa ng client. Pilitin ang client timeout, tapos ulitin ang parehong request sa loob ng TTL ng key. Buksan ang prepaid ledger: ang intent na iyon ay dapat magpakita ng isang debit at isang mensaheng nakikita. Dalawang hilera ang ibig sabihin ay hindi nabuhay ang key sa retry — ayusin ang TTL at handler bago manatiling Live ang corridor.

Buod ng IOSOR

Gawin: unahin ang bawat send bilang ledger event.

Nakatulong ba ang gabay na ito?

Mga kaugnay na gabay