How-to · 3 min read
Idempotency keys: safe retries for order creation
Never double-buy a number on a retry. How idempotency keys work and how to use them when creating orders.
Networks fail mid-request. If you retry a create-order call without protection, you can buy two numbers and pay twice. Idempotency keys fix that.
How it works
Send a unique Idempotency-Key with the create call. If the same key arrives again within 24h, the server returns the original order instead of creating a new one.
await eveses.orders.create(
{ country: 'ua', mode: 'activation', service: 'telegram' },
{ idempotencyKey: `signup-${userId}-${attempt}` },
);
Choosing a key
- Make it unique per logical operation, not per HTTP attempt — reuse the same key across retries of the same signup.
- Good sources: a job ID,
signup-{userId}, or a UUID you persist before the first attempt.
This is the Stripe pattern — safe to retry, exactly-once effect.
Ready to build? Create a free Eveses account, top up a wallet, and grab your API key — no KYC. See the API docs or live pricing.
FAQ
▸What is an idempotency key?
A unique value you send with a request so that retrying it returns the original result instead of creating a duplicate — here, it prevents double-buying a number.
▸How long is the key cached?
For 24 hours — a repeat within that window returns the original order.
Related guides