Skip to main content
Send an Idempotency-Key on a write, and a retry carrying the same key gets the first attempt’s answer back — the same status and body, and the same Location on a create — rather than performing the write twice. Every write an integration makes honours it: creating, changing and removing listings, recording a shipment, and changing a business’s details. So do the app’s orders and payments, messaging, the address book, favorites, saved searches, single notifications and devices. The rest ignore the header: changing or closing the account, signing up, resetting a password, verification mails, second factors, linked sign-ins, ending sign-ins, marking or clearing the whole bell, test pushes, and uploads.
string
A UUID per logical operation, not per attempt: every retry of the same write carries the same key. Any string of up to 191 characters is accepted; a longer one is refused with 400 and idempotency_key_invalid. Honoured for 24 hours, and scoped to your client — and to the person, when a person is signed in — so you cannot collide with anyone else.

What comes back

The original status and body, with Idempotent-Replay: true on it. Nothing happened a second time.
422. The same key on a different request — another method, path or body. Refused: reusing a key for something else would hand you an answer to a question you did not ask.
409. The first attempt is still running. Wait and try again — do not race it.
409. The key expired between the first attempt and this one, so we no longer know what we answered. Retry with a new key.
A key is released if we answered with a 5xx, so a server error can simply be retried.
Generate the key when you decide to make the write, not when you send it. A key generated per HTTP attempt is the same as no key at all.