Idempotency Keys

You've probably clicked a 'Pay Now' button twice because the page seemed frozen. Then you worried you had just been charged twice. An idempotency key fixes that. It's a unique ticket number the app attaches to that one purchase attempt. The server keeps a log of ticket numbers it has already handled. Say the same ticket number shows up again, because the click — or a network retry — got sent twice. The server doesn't charge you again. It just hands back the same result as last time, as if it never ran the action twice.

1. 1Before sending a request that changes something, like 'charge this card,' the client generates one unique key for that attempt. It attaches the key to the request.
2. 2The server checks a lookup table: has this exact key been seen before? If yes, skip the action. Just return the result saved from the first time.
3. 3If the key is new, perform the action for real. Save the key and its result together. Then return the result.

Use idempotency keys once your app is popular enough that flaky networks, slow pages, or retry logic start sending the same request more than once. Payments, placing an order, and sending a signup email are exactly the kind of action you never want to run twice by accident.

• ⚠Generating a brand-new key every time you retry, instead of reusing the same key for the same attempt. That defeats the whole point — the server can no longer tell it's a repeat.
• ⚠Remembering only that 'this key was used,' without saving the actual result. Then a retry can't get back the original answer it needs, like the order ID.