# Idempotency & retries

When a request times out you cannot tell whether it reached us. Retry it — with the same `Idempotency-Key`, so a second copy cannot act twice.

## `Idempotency-Key`

Every `POST` accepts an `Idempotency-Key` header: any unique string of 1–255 printable ASCII characters, for example a UUID you generate per operation and **store with it**, so a retry sends the same value. Anything else → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field).

| Retry with the same key | Answer |
|---|---|
| Same request, first one finished | The **stored first answer** — same status, same body byte for byte, same `ETag` and `Location` — with `Idempotent-Replayed: true`. Nothing runs again. |
| Same request, first one still running | [`409 idempotency_in_progress`](https://docs.creator-guard.com/errors/#idempotency_in_progress) — wait a second and retry. |
| Different path or body | [`422 idempotency_key_reused`](https://docs.creator-guard.com/errors/#idempotency_key_reused). Use a new key for a new operation. |

"Same request" means the same path and the same body bytes: send the stored body again rather than serialising it anew.

Answers are kept for **24 hours** per API key: another key of the same account (a colleague's, or the new key after a roll) never gets your stored answer, and the same request sent with it runs anew. What the endpoint itself answers is stored, `2xx` and `4xx` alike, except `429`; `5xx` and `429` answers never are, so a retry after a `500` or a `429` runs again. A request refused before the endpoint runs — key, scope, rate limit, terms or a malformed body — stores nothing, so once you fix the cause the same key works. `PATCH` takes no key: sending the same change twice has the same result.

## `external_id` — idempotency that never expires

`POST /v1/leads` also recognises your own reference: a second create with an `external_id` you already used returns that lead (`200`) unchanged, even days later and without an `Idempotency-Key`. Use both: the key for safe retries, `external_id` so an import that loses its keys still cannot create a creator twice. Duplicate rules by Instagram handle: [Leads](https://docs.creator-guard.com/leads/#duplicates).

## A retry loop

1. Generate the `Idempotency-Key` once per operation and keep it.
2. On a timeout, a network error, `409 idempotency_in_progress`, `429` or `5xx`: wait and retry with the **same** key and body. No `429` is stored, `429 duplicate_limit_reached` included, so after `Retry-After` the same key runs the request again.
3. Wait `Retry-After` seconds when the answer has that header, otherwise back off exponentially (1 s, 2 s, 4 s, … up to a minute).
4. Never retry other `4xx` answers unchanged: fix the request first.
