What is idempotency — and why the card got charged twice

Here's an unpleasant thing rarely explained to beginners: a double card charge usually happens not because the user tapped the button twice.
They tapped once. The request reached the server. The server charged the card and started replying "done" — and right then their connection blinked. The reply never arrived. Their phone assumed the request was lost and politely sent it again. The server received a second, identical request and charged again, because as far as it knew this was a brand-new ask.
The property that protects you from this is called idempotency. It sounds like textbook vocabulary — it's actually the most practical idea in anything that touches money or data.
The one-line definition
An idempotent operation is one where repeating it changes nothing.
Compare two requests:
- "Set the volume to 5" — repeat it a hundred times, the volume stays 5. Idempotent.
- "Turn it up by one" — a hundred repeats and you're deaf. Not idempotent.
Same with data. "User 7 is now named Anna" — repeat it forever, one result. "Create a new user named Anna" — repeat it three times, get three Annas.
Where the retry nobody made comes from
The key idea: a repeated request is normal, not a malfunction. It happens on its own, with no human involved, for at least three reasons.
- A lost reply. The request arrived, the work happened, the reply didn't come back — the connection dropped or a timeout fired. The client can't tell "never arrived" from "arrived, reply lost," so by default it tries again.
- Automatic retries. Mobile libraries, server-side HTTP clients, job queues — nearly all of them retry on a network error. Often you don't even know it's happening.
- Webhooks. Payment and email services guarantee "at least once" delivery: if your server was slow or returned an error, the very same webhook arrives again. And again. That's designed behaviour, not a bug.
An uncomfortable but useful conclusion: if your payment handler isn't ready to see the same request twice, one day it will.
Which requests are safe by themselves
HTTP builds this into the meaning of its methods — and this is exactly where beginners slip:
GET— reads. Repeat all you like.PUT— "let it be this way." A repeat lands on the same state. Idempotent.DELETE— "let this not exist." The second time there's nothing left to delete, same state. Idempotent.POST— "create one more." Not idempotent — and it's what payments, orders and signups hang on.
A useful habit: write "set this value" instead of "add one." PUT /cart/items/42 {quantity: 3} is safe, while a repeated POST /cart/add drops an extra item into the cart. There's a separate breakdown of what the response codes mean.
How to make POST idempotent
The whole idea lives in one move: let the client name the operation, and let the server remember the name.
- When building a payment, the client generates a random identifier — a plain UUID — and puts it in a header. Payment APIs standardised this: at Stripe the header is
Idempotency-Key. - On receiving the request, the server first checks: has an operation with this key already run?
- If not — run it, and store the result next to the key.
- If yes — do not run it again, return the stored response. The client sees "done" and calms down.
One critical detail: the key is generated once per payment attempt, not per network request. Otherwise the retry carries a new key and the whole point evaporates.
Plus a safety net at the database level: a unique index. If an order has a payment_id column, mark it UNIQUE — then a second insert simply can't land, even if your logic slips somewhere. It's the same move that guards against two simultaneous requests racing.
What to do about it right now
Open the handler in your project that creates something important — a payment, an order, a credit — and ask it one question: what happens if this exact request arrives again a second later? If the answer is "a duplicate gets created," there's a hole, and you can see it before any users do. How to wire up payments so this question gets asked in time — see the payments guide.
Is idempotency the same as "exactly once"?
No. "Exactly once" over a network is practically unattainable; delivery is guaranteed "at least once." Idempotency is how you live with that: let the request arrive three times, the effect equals one.
How long should idempotency keys be kept?
A day is plenty — retries happen within seconds or minutes. Stripe, for example, keeps keys for 24 hours; that's a good benchmark for your own project.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





