Edge and reliability / Intermediate / 6 min
Retries and idempotency keys
A lost reply makes the client retry a payment. Watch double charges pile up, then stop with an idempotency key.
Start the simulation → Change the load, break a part, watch what happens. Free, no sign-up.
In short
- What it is
- An idempotency key is a unique id the client sends with a request, so the server can recognise a retry of the same operation.
- Why it matters
- A timeout cannot tell a lost request from a lost reply, so clients must retry, and without a key a retried payment is charged twice.
- The trade-off
- The server must store each key with its result for a while (often 24 hours) and handle two copies arriving at the same moment.
- Say it in an interview
- "The client sends an Idempotency-Key per payment; the server saves the result under it in the same transaction and replays it for retries."
Check yourself
A payment request times out on the client. What does the client actually know?
Answer: Nothing: the request or only the reply may have been lost. A timeout looks the same whether the request never arrived or the server charged the card and the reply was lost. That is why retries need idempotency.
How does an idempotency key stop a double charge?
Answer: The server stores the result under the key and returns it again for a repeat. The first call charges and saves the result under the key. A retry with the same key gets the saved result and no new charge.
Who should create the idempotency key?
Answer: The client, once per payment, reused for every retry of it. The key must be the same for every retry of one payment, so the client creates it before the first attempt (Stripe sends it in the Idempotency-Key header).