checkout.com idempotency key reused with different payload: 422
Fixes Checkout.com 422 errors from reusing an idempotency key with a different payload. Use when a retry returns 422 instead of the original result, usually because the retry body drifted from the first attempt. Not for auth errors or validation failures on first attempts.
checkout.com idempotency key reused with different payload: 422
TL;DR
Idempotency keys are bound to the exact request body. You sent a key that was already used, but with a different payload, so Checkout.com refused it with a 422. Regenerate the key whenever the payload changes, and make your retries resend the byte-identical body.
checkout.com idempotency key reused with different payload: 422Steps
- Confirm the 422 is the idempotency conflict and not a validation error: the key was used before with different content. Success check: your logs show the same key with two different bodies.
- Decide intent: if this is a retry of the SAME request, resend the original body unchanged. Success check: the retry returns the original result instead of 422.
- If the payload genuinely changed, generate a new idempotency key for the new request. Success check: new key plus new body returns a fresh result.
- Fix the key generator: derive the key from a hash of the request body (plus order id) so identical retries reuse the key and changed requests cannot. Success check: no key is ever sent with two different bodies.
- Audit recent 422s to confirm no duplicate payments were created by key regeneration during confusion. Success check: every order has exactly one successful payment.
When this applies
- Checkout.com returns 422 when you reuse an idempotency key with a changed payload.
- Retries fail while first attempts succeed.
- An agent regenerates keys per retry attempt.
When it doesn't
- 422s on first attempts with a fresh key; that is a validation error.
- 401/403 errors; those are authentication, not idempotency.
- Duplicate charges with distinct keys; that is a retry-design problem.
Tool + version compatibility
Checkout.com API idempotency (all current API versions).
"checkout.com 422 idempotency key"
Same key plus different body always 422s; fix the key or the body.
"checkout.com idempotency conflict different payload"
Decide: identical retry keeps the key, changed request gets a new one.
"checkout.com idempotency key already used"
Replay the original body to get the original result back.
Why it happens
An idempotency key tells the gateway: this request is the same one you already saw. If the body differs, the gateway cannot honor that promise, because it cannot know which body is the real intent. So it rejects with 422 rather than guessing. Agent retry loops commonly regenerate keys per attempt (fine) or mutate the body between retries while keeping the key (not fine).
Edge cases / pitfalls
- Hashing the body into the key is the durable fix; human discipline is not.
- A 422 on an idempotent replay is safe to retry with the original body; it created nothing.
- Do not suppress 422s in a generic retry loop; each one is telling you the key/body pairing is wrong.
- Keep the original request body for the life of the key so retries are byte-identical.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_-DlhHZdVNUScAVOoFtA7LQ