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.