How the Idempotency Saves the ?

Imagine a Sunday afternoon in March 2019. Someone in India tries to order food on Uber Eats with Paytm. Their wallet is empty, the payment errors. They tap order again. The food arrives anyway. Word spreads. Within hours, a college in India has run up $14,000 in free orders — in a single day. Uber only finds out when restaurants start going offline under the order volume.

The cause was a tiny change at Paytm: an API endpoint silently went from idempotent to non-idempotent. Uber's integration assumed the old contract still held; the new response Paytm returned wasn't mapped to anything, and the silent default was treat it as success.

This was not a security breach. It was a missing contract: the agreement between client and server that says if you see this request again, treat it as the same one, not a new one. That contract has a name: idempotency. Without it, the web is a sea of retry-happy clients sending duplicate requests no one can recover from. With it, everything keeps working through failure.

GET: Reads Don't Break Things

What you see on the left is the Retry Lab. A client. A server. A wire between them. Below the wire, two panels: the request log is what the client perceives — what requests it sent, what it got back, what it does not know. The server resource is what is actually true on the server. The reason we need both panels is the entire point of this post: sometimes they tell different stories.

Throughout, the same resource lives on the server — a bank account.

{ "id": "acc_42", "owner": "Alice", "balance": 100 }

We will send requests to read and mutate this account, retry them, break the wire mid-flight, and watch what happens. The first scenario is the simplest one: a successful GET. Nothing breaks. Nothing changes server-side.

That is the baseline. GET is safe^* — it cannot change the server. And it is idempotent — even if you fire ten GETs back to back, the server is in exactly the state it started in. Most other methods will not be this polite.

Idempotency Is About Server State, Not the Response

Most engineers can recite the textbook definition of idempotency: an operation is idempotent if running it multiple times has the same effect as running it once. Fine. The trap is in the word effect.

Effect on what?

Effect on the server's state, not on the response you receive. A method can return a different response each time it runs and still be idempotent — as long as the server ends up in the same place.

DELETE makes this obvious. Watch:

First DELETE: the account exists, the server deletes it, returns 204 No Content. Second DELETE: the account is already gone, the server returns 404 Not Found. Two completely different status codes. Same server state both times: gone.

That is idempotent.

This also reveals something else: safe and idempotent are not the same property. GET is safe (no state change) and idempotent. DELETE is idempotent (gone twice is still gone), but it is absolutely not safe (it destroyed the account). POST is neither safe nor idempotent. Hold onto that distinction — you will need it in about thirty seconds.

The Wire Breaks → POST: The Double-Charge Trap

In the real world, requests fail. They fail in two distinct ways, and the second one is the entire reason this post exists.

Failure mode 1 — the request is lost. The packet leaves the client and never arrives. The server does nothing. No state change. From the client's side: silence.

Failure mode 2 — the request reaches the server, the server processes it, and the response is lost on the way back. The server has done the work. The client never finds out.

Here is the cruel part: from the client's perspective, both modes look identical. Both feel like "I sent a request and got nothing back." But the server's reality is wildly different in each case — and you have to decide whether to retry without knowing which world you're in.

Now watch what happens when the retried method is POST.

Two Alices. One user intent, two records on the server. This is the canonical failure that makes idempotency necessary, and this is exactly what happened to Uber Eats — at scale. A third-party payment API's retry-status was mis-read; the same payment kept landing again; the food kept getting delivered; the money kept not getting charged.

PUT: Same Failure, Different Outcome

Now the same broken wire, the same retry, the same intent — but with PUT.

Watch what just happened. The network broke in exactly the same way. The client retried in exactly the same way. The server received the same request twice — exactly like before. The outcome is different: one record on the server, balance 200, exactly as if the client had sent one PUT.

The difference is the method's contract. PUT says: here is the new full state of this resource — make it look like this. Two PUTs with the same body land the resource in the same place as one PUT. The retry is a no-op on state. That is what idempotent means in practice, and that is why PUT survives where POST does not.

PATCH: The Trap Inside the Trap

Is PATCH idempotent? The honest answer is: it depends on what the patch body does.

PATCH is a partial update. The verb itself does not specify how you describe the partial update. You could say "set this field to 200" — a declarative patch. You could say "add 50 to this field" — an imperative, delta-style patch. Both are valid PATCH bodies. They behave very differently under retry.

Start with the declarative one.

Same body, same outcome. { balance: 200 } sets the balance to 200 — twice in a row, still 200. Just like PUT, but with a smaller payload. So far, PATCH looks idempotent.

Now change one word in the body.

The balance is 200 instead of 150. The retry doubled the credit. Same client intent — but the body says add, not set, and the server obediently adds twice. Your user wanted a single $50 deposit; they got a single $50 deposit's worth of side effect, applied twice.

So here is the interview answer, distilled: "PATCH's idempotency is determined by the patch body, not by the verb. A declarative {balance: 200} is idempotent — functionally a small PUT. An imperative {credit: 50} is not — deltas accumulate under retry."

Idempotency Keys: Making POST Survivable

Sometimes the operation you need genuinely cannot be idempotent. POSTing a payment, charging a card, sending an email — these are creation events with side effects in the real world. PUT is not what you want. So how do you retry POST safely?

You attach an idempotency key: a unique identifier the client generates per logical operation, sent as an HTTP header. The server keeps a small table of seen keys mapped to the responses it returned. When a request arrives with a key it has seen before, the server skips the work and replays the cached response.

Same broken wire as before. Same retry. But this time the second POST is recognized — the key 9b3f… is in the server's dedupe table — and the server skips the create entirely. The client gets the cached 201. One account on the server. Crisis averted.

This pattern is what Stripe famously documented and what most well-designed payment APIs require for retries. Done right, it gives POST the safety of PUT without losing its creation semantics.

Back to Uber Eats: The Missing Idempotency Key

This is exactly the missing piece in March 2019. Paytm silently changed the behavior of a charge-retry endpoint — what used to be idempotent stopped being so. Uber Eats had no way to recognize that the second hit on a failed payment was a retry of the first; the response shape was new, the silent default mapped it to success, and the food kept getting delivered.

The fix — both then, and in any system that takes retries seriously — is a key-based contract between client and provider, where every payment attempt carries an idempotency key, and the provider's response is anchored to that key. Under that contract, the same retried payment is unambiguously the same payment, regardless of what new response the provider introduces next quarter.

reddit

HTTP methods are promises you make about your endpoint's behavior, and the infrastructure of the web assumes you keep those promises. Idempotency isn't something HTTP grants for free to verbs like GET, PUT, or DELETE — it's a property you uphold through how you write the handler and how you design the contract. Break that contract and you can certainly do it — but you've made your endpoint un-cacheable, un-retryable, and dangerous in the face of the very behaviors the contract was designed to enable safely.