> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wristler.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrying safely

> A network error tells you nothing about whether the write landed. This header does.

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.

```http theme={null}
POST /v1/sellers/42/watches
Idempotency-Key: 0b6d1f4a-9c3e-4f8a-8d21-6e5f7a0c1b93
```

**Idempotency-Key** `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

> [accordion] A replay
>
> The original status and body, with `Idempotent-Replay: true` on it. Nothing
> happened a second time.

> [accordion] idempotency\_key\_reuse
>
> `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.

> [accordion] idempotency\_in\_progress
>
> `409`. The first attempt is still running. Wait and try again — do not race it.

> [accordion] idempotency\_conflict
>
> `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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.