> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency key conflict

# `idempotency_key_conflict`

| HTTP | When                                                                                 |
| ---- | ------------------------------------------------------------------------------------ |
| 409  | The `Idempotency-Key` was already used for a different request body in the last 24h. |

Idempotency keys are scoped to `(workspaceId, route, key)` and stay
valid for **24 hours**. The first request under a key is recorded with
a SHA-256 hash of its canonicalised JSON body. Any later request with
the same key but a different body is rejected with this error so we
never silently merge two distinct operations into one cached response.

## What it usually means

You're reusing a key on purpose for distinct operations. The fix is to
mint a fresh `Idempotency-Key` (a UUID is the easy default) per logical
operation. The same key is appropriate **only** when retrying a literal
duplicate of an unchanged body — typically because of a network error
where you're not sure whether the original request landed.

## What it sometimes means

Your client modified the body before retrying — e.g. added a current
timestamp, a retry counter, or shifted formatting. Canonicalisation
sorts object keys but does not normalise values. If your retry serialises
`scheduledFor` as `"2026-06-01T13:00:00Z"` the first time and
`"2026-06-01T13:00:00.000Z"` the second time, the hash differs and you
hit this error.

The pragmatic remediation: derive the key from a stable hash of the
*intended* operation, never from the wire body.

## Recovery

1. Generate a fresh key and resend the request.
2. Or wait 24h for the key to expire (rarely the right move in
   production — the previous response is no longer recoverable once it
   has expired).

See [Idempotency](../idempotency.md) for the full contract.