🔑 An Idempotency-Key is now scoped to the request that created it. Presenting a key alongside a different method, path or body returns 409 Conflict with the idempotency_key_mismatch code instead of replaying the unrelated first response. Retries of the identical request keep replaying as before.
📚 Document the header, which has been supported all along but was never written down. The new Idempotency section explains how to retry a write safely: the first response is stored and replayed to any later attempt at the same request, so a request that was applied but whose response never reached you is not applied twice. It also covers what is not stored (4xx and 5xx, so those retries genuinely re-run) and the one sharp edge — concurrent requests sharing a key are both processed. API best practices now recommends retrying 5xx with a backoff and a stable key instead of aborting the whole synchronization.
