Idempotency
Retry a purchase safely, without buying twice.
A network error can leave you unsure whether a purchase went through. Every POST /offsets therefore requires an Idempotency-Key header: a unique value per purchase, such as a UUID.
Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0fWhat happens on a retry
| You send | You get |
|---|---|
| A new key | A new purchase (201). |
| The same key and the same body | The first purchase again (201), with Idempotent-Replayed: true. Nothing is bought twice. |
| The same key and a different body | 409 idempotency_key_reused. Use a new key for a new purchase. |
The replay returns the purchase as it is now, so its status may have moved from processing to placed.
Good to know
- Keys are 1 to 255 printable ASCII characters, and we remember them for good, per mode.
- Body key order and spacing don’t matter:
{"kg":1,"reference":"a"}and{ "reference": "a", "kg": 1 }are the same request. - A purchase that fails (for example
402 insufficient_balanceor a validation error) stores nothing. After you top up, you can retry with the same key. - Two requests with the same key at the same moment are safe: one buys, the other gets the replay.