• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

API and integration

Idempotency key

An idempotency key is a client-chosen identifier sent with a request so that retrying it after a timeout or error returns the original result instead of sending the message twice.

Networks fail at the worst moment: after the server has acted and before the client hears about it. A request that times out may or may not have sent the message, and the client cannot tell which. Without idempotency, the safe reaction is to do nothing, and the tempting one, retrying, risks a duplicate. With an idempotency key the client retries freely: the server recognises the key, returns the result of the first attempt and sends nothing new.

The Idempotency-Key header is a convention popularised by payment APIs and widely adopted since. Servers keep keys for a limited period, and many refuse a key that comes back with a different payload, since that signals a client bug rather than a retry. The key should come from your own business identifier, an order number plus the event, or a user plus the attempt, so that retries from different processes or servers collide correctly. It must be created before the first attempt, stored with the job and reused unchanged on every retry.

Example

A hypothetical shop sends a shipping notice for order 4821 with the key order-4821-shipped. The first POST times out. The retry, with the same key, returns the original message id and status; the customer receives one SMS and the account pays for one. Had the retry used a fresh key, the customer would have received two.

Common mistakes

  • Generating a new random key on each retry, which defeats the purpose.
  • Using a key that is too broad, such as the user id alone, so that later, different messages are treated as replays and never sent.
  • Creating the key inside the retry loop instead of persisting it with the job.

At SMSMeteor: any POST accepts Idempotency-Key, a string of up to 128 characters chosen by you. Same key and same payload within 24 hours: the original response is returned, with the header Idempotent-Replayed: true. Same key, different payload: 409 idempotency_conflict. That matters because a message is billed once it is handed to a carrier, so a duplicate would be a second charge. After a 429, wait for Retry-After and retry with the same key. The API reference has the details, and a test key lets you rehearse timeouts and retries without sending anything.

Go further

See the term in practice.An email address opens the account, the rate card is public, payment is crypto, the test key is free.
Start sending