™2 min read
What triggers it
An idempotency key was reused with a different body. Sending a new request body under a key already used for a different one.
Example response
{
"error": {
"type": "invalid_request_error",
"code": "idempotency_key_reused",
"message": "An idempotency key was reused with a different body.",
"param": "Idempotency-Key"
}
}How to fix it
Use a fresh key per distinct operation; reuse the same key only for identical retries.
This is deterministic: the same request will fail again until fixed. See the HTTP 409 page for the class.
In practice
In a well-built client, idempotency_key_reused is handled by branching on error.code rather than on the human error.message, which may be reworded over time. The HTTP status (409) gives the broad invalid_request_error class; the code gives the specifics; and, on field errors, error.param pinpoints the input to fix.
This code is deterministic — retrying the identical request reproduces it — so keep it out of your retry path and instead map it to a clear, actionable message. See Map errors to user-facing messages and Read the error envelope for the pattern.
Frequently asked questions
Is idempotency_key_reused safe to retry?
No. It is deterministic; retrying the identical request produces the identical error. Fix the cause first.
Will this code ever change?
No. Error codes are stable contract. The human message may be reworded, but the code you branch on will not change.
Do I branch on the code or the HTTP status?
Both — the status for the retry-or-not decision, the code for the specific behaviour. See the error envelope.
Funding for UK limited companies
Credicorp lends to your company, not to you personally — short-term working capital with no personal guarantee. See what your business could access.