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

# Idempotency

> Send Idempotency-Key on every write to make retries safe.

Network failures happen. Klikit's writes are designed to be safely retried
when you pass an `Idempotency-Key` header — the same key with the same body
returns the original response, instead of executing the action twice.

## How to use it

Generate a fresh UUID (or any unique string up to 64 chars) per logical
operation and send it on writes:

```bash theme={null}
curl -X PATCH \
  -u "$KEY:$SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8e3f4a18-7e7d-4d2c-9d2b-1a..." \
  -d '{"available": false}' \
  "https://api.dev.shadowchef.co/v1/partner/items/sku-42/availability"
```

If you retry the **same key + same body** within 24 hours, klikit replays the
recorded response — no second write hits the underlying system.

If you retry the same key with a **different body**, klikit returns
`409 IDEMPOTENCY_KEY_CONFLICT`. That's your signal that your retry logic and
your client both think they own the key — investigate before retrying.

## Which endpoints honour it

| Endpoint family                  | Idempotency-Key                           |
| -------------------------------- | ----------------------------------------- |
| `PATCH /items/{id}/availability` | ✅ honoured                                |
| Bulk OOS                         | ✅ honoured                                |
| Visibility writes                | ✅ honoured                                |
| All reads                        | ✖️ ignored (reads are already idempotent) |

## Practical recipe

* Generate the key **once** at the boundary where you decide to perform the
  action (e.g. when the operator clicks "mark out of stock"), and reuse it
  across all retry attempts of that one logical action.
* Do **not** regenerate the key on each retry — that defeats the safety.
* Keep your retries to a finite count with exponential backoff. Klikit
  remembers the key for 24 hours; after that the dedupe window has closed.