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 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.