Skip to content

API & developers

Idempotent orders

Send an Idempotency-Key so a retried request never buys two numbers or two rentals. How keys behave, and what a conflict means.

Last updated
Updated
Reading time
1 min read
On this page3
  1. How to use it
  2. What happens on a retry
  3. Good to know

Networks fail at the worst moments. Your request to create an order times out, and you can't tell whether it went through. Retrying blindly could buy two numbers. An idempotency key makes the retry safe.

How to use it

Send a unique Idempotency-Key header with every POST /api/v1/orders — and with every POST /api/v1/rentals, which works the same way:

Shell
curl -X POST https://passcode.sh/api/v1/orders \
  -H "Authorization: Bearer $PASSCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1f0a2e-8a43-4f8e-9a51-3d2c7b0e9f14" \
  -d '{"service": "telegram"}'

Generate a fresh key — a UUID is ideal — for each order you mean to create, and reuse it only to retry that same request.

What happens on a retry

Situation Result
First request with this key The order (or rental) is created and charged as normal.
Same key, same request You get the original back, with an Idempotent-Replayed: true header. Nothing is charged again.
Same key, different request — another service, country or max_price Refused with idempotency_conflict (HTTP 409). Nothing is charged.
Two requests with the same key at once One creates it; the other returns that same one.

Good to know

  • Keys belong to your account and can be up to 255 characters long. Orders and rentals keep separate keys.
  • Keys don't expire. A key, once used, always refers to that one order or rental — so never reuse a key for a new purchase.
  • A replay is returned in its current state, so by the time you retry an order may already be received, completed or expired.
  • Replays don't count towards the per-account limits on new orders and rentals.

Tip

Persist the key with your own record of the purchase before sending the request. If your process crashes mid-request, the retry after restart uses the same key and can't double-buy.