Code10x
Idempotencyhard3-5 years

How would you design an Idempotency-Key mechanism for a POST /charges endpoint so a retried request can't double-charge a customer?

The client generates a unique key per logical operation (typically a UUID) and sends it on every attempt via an Idempotency-Key header. The server stores the key together with the response it produced; a request that arrives with a key already marked complete gets the stored response replayed, not a fresh computation — same chargeId, no second charge. A key reused with a different body is a client bug, not a retry, and should get a 409/422, not a silent replay, because replaying then would hide the mistake instead of catching it.

The lesson behind it →
PreviousWhy does offset pagination return duplicate or missing rows under concurrent writes, and how does keyset pagination avoid it?Next Compare token bucket and sliding-window-counter rate limiting. Which would you reach for on a public API, and why?
More on Idempotency
Two identical POST requests carrying the same Idempotency-Key arrive at the same instant on two different instances. Walk through why wrapping the check-then-insert in a database transaction doesn't prevent a double-charge, and what does.