Errors
validation_idempotency_key_conflict
409 — an Idempotency-Key was reused with a request body that differs from the original.
Last updated
Cause
Matter requires an Idempotency-Key header on every mutating verb and retains the key for 24 hours scoped per token. A second request with the same key returns the stored response from the original — that is the entire point of idempotency. validation_idempotency_key_conflict fires when the second request supplies the same key but a body that hashes differently from the first.
This is a safety mechanism. Reusing a key with a changed body is almost always a programming mistake — the caller is treating the key as a request id rather than as a bound contract over (method, path, body). Matter refuses to replay the original response and refuses to execute the new one under the same key.
Fix
- Mint a fresh
Idempotency-Key(UUID v4) per logical operation. Two different requests must never share a key, even if they look similar. - When retrying the same logical operation, send the same key with the same body. The retry returns the stored response.
- When the body legitimately changes — for example, adding
acknowledgements[]after the first attempt returned a 422 — generate a new key. - Persist the key alongside the operation's outcome so retries on intermittent network failures can replay safely. Never derive the key from the body's hash; that defeats the contract.
Related codes
validation_header_invalid— the key header is malformed or absent.state_transition_invalid— the original request succeeded and a follow-up transition is now rejected.state_optimistic_lock_conflict— a concurrent write hit the same resource.