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

# Idempotency

> Retry a write safely with an Idempotency-Key.

Networks fail. If a write times out you cannot tell whether it happened. Send an `Idempotency-Key` header on a `POST` that changes data and repeat the exact same request if you did not get an answer:

```bash theme={null}
curl https://api.brandgate.dev/v1/price_lists \
  -H "Authorization: Bearer $BRANDGATE_API_KEY" \
  -H "Idempotency-Key: pl-painters-2026-10-21T08:00" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"PL-PAINTERS","name":"Painters"}'
```

* The key is 1 to 64 characters: letters, digits and `_ . : -`. Use a new key for every new request, for example a UUID.
* **Same key, same body:** you get the first answer again, with the header `Idempotent-Replay: true`. Nothing is done twice.
* **Same key, different body:** `409 idempotency_key_reused`.
* **Same key while the first request is still running:** `409 idempotency_in_progress`, with `Retry-After`. Wait and retry.
* A request that failed (a `5xx`, or a network error) can be retried with the same key and runs again.
* Keys are remembered for 24 hours, per API key.

Product, price list and customer upserts are already safe to repeat because they send state, so the header is a convenience there. It matters most for [`orders/{id}/acknowledge`](/guides/erp-sync) and for your own retry wrappers.


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