Idempotency

Anything that spends money requires an Idempotency-Key header: buying an activation, renting a number, extending a rental, reporting a missing code, and cancelling.

Idempotency-Key: 8f3a2c1e-4b7d-4f90-9c11-2a6e5d0b7c31

Generate one per attempt — a UUID is ideal — and reuse it for every retry of that attempt. Any printable ASCII up to 255 characters is accepted, so your own order id works too, as long as it is unique per purchase.

What a retry returns#

The first request with a key does the work and stores the outcome. Any later request with the same key returns that stored outcome instead of doing the work again — the same status, the same body, plus a header saying so:

Idempotent-Replayed: true

So a timeout is safe to retry. If the first call bought a number and the response never reached you, the retry hands you that number rather than a second one.

An outcome is replayable for 24 hours. After that the key is forgotten and a request carrying it is treated as new.

Two rules worth knowing#

The key is tied to the request you sent. If you reuse a key with a different body or a different path, you get 422 and idempotency_key_reused rather than a confusing replay — reusing a key for a different purchase is a bug, and silently answering it would hide that bug.

A retry that arrives while the first is still running gets 409 and idempotency_request_in_progress. Wait and retry; do not generate a new key, because a new key means a new purchase.

Where it does not apply#

Reads. GET endpoints change nothing, so they need no key and none is accepted.