# Idempotency

When a client supplies a unique key (`X-Idempotency-Key`, UUID). The header is **optional**:
if it is omitted the request is processed
normally  (no deduplication, no replay). Supplying the header is strongly recommended for POST
operations that create side effects.

Provide optional `X-Idempotency-Key` on POST writes for safe retries:

- Success → cached and replayable.
- In-flight duplicate → 409 (retry later).
- Mismatch → 422.
- Failure → entry removed (safe retry).
- Only successes are replayed.


### With vs Without the Header

With `X-Idempotency-Key`:

- First request claims and (if successful) caches response.
- Concurrent duplicates while in flight receive 409 + `Retry-After: 1`.
- Later identical retries get the cached 2xx response.
- Different payload/path/method using same key → 422 mismatch.


Without the header:

- Filter bypasses idempotency entirely.
- Each call executes independently; duplicates may create repeated side effects.