Send API idempotency: duplicates, retries, and money

Timeouts happen. Load balancers retry. Mobile clients double-tap. Without idempotency, a «send once» product becomes a prepaid double charge with duplicate OTP UX. This guide is for engineering and technical product leads integrating a white-label prepaid messaging API — where every duplicate is visible in the wallet. IOSOR expects money-aware integrations: authenticated calls, correlatable debits, and client errors that never dump foreign brand payloads. Closer commercial intensity around about USD 1,000+ monthly platform usage makes duplicate discipline non-optional.

Why duplicates become money problems

Idempotency keys that survive retries

A serious send path accepts a client-generated key (or equivalent) that is unique per business intent, not per TCP attempt. It must return the same accepted result on replay within a clear TTL window. This prevents silently creating a second debit for the same intent. The key should be logged next to the message ID and the prepaid reference. It must work across timeouts, gateway retries, and support redrives.

Retry budgets vs user resend

Automatic retries need a budget: max attempts, backoff, and which error classes are retryable. User-initiated resend is a different product action with its own rate limits and prepaid cost. Mixing them is how a flaky network becomes a weekend wallet event. Pair both with stop-on-low-balance and clear reject reasons so product and finance share one truth.

Buyer / engineering checklist

1. Documented idempotency key semantics and TTL.
2. Replay test that proves one debit for one intent.
3. Separate auto-retry budget from user resend logic.
4. Correlation IDs across request, message status, and prepaid ledger.
5. Staging that exercises real corridors — mock green lights are not launches.
6. Key hygiene and least privilege for send credentials.
7. Handling of 429 and 503 codes without losing the original intent key.
8. Automated alerts for high duplicate-key rejection rates.

Red flags

• «Just retry until 200» without using idempotency keys.
• Webhook handlers that are not idempotent and trigger side effects twice.
• Full secret keys or auth tokens appearing in logs or support tickets.
• Errors pasting upstream brand payloads or internal stack traces to end users.
• No way to prove to finance that a specific duplicate was prevented.
• Using timestamps as the only source of uniqueness for transactions.

Start with IOSOR

In the send console, fire one OTP or alert with a client-generated idempotency key. Force a client timeout, then replay the identical request inside the key TTL. Open the prepaid ledger: that intent must show one debit and one user-visible message. Two rows means the key never survived the retry — fix key TTL and the handler before the corridor stays Live.

• webhooks that survive launch
• API rate limits from pilot to production
• NANP Overlays Before You Send: Data Quality for Finance

IOSOR takeaway

Do: treat every send as a ledger event first. The idempotency key is unique per business intent, not per TCP attempt. Auto-retry has a budget; a user tap on resend is a different product action with its own prepaid cost.

Don't: hammer until 200 without a key, or let a non-idempotent webhook mint a second side effect. Two OTPs for one tap is a money bug, not a network story.