---
title: Idempotency
description: Retry a purchase safely, without buying twice.
sidebar:
  order: 4
---

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.

```txt
Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f
```

## What 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_balance` or 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.