A customer taps “Pay ₹2,499” in a shopping app on a patchy 4G connection. The app sends the request, waits ten seconds, and gets nothing back. Did the payment go through? The app cannot know. The request may never have reached the server, or the server may have charged the card and the response got lost on the way back. If the app retries, it might charge twice. If it doesn’t, it might leave a paid order looking unpaid. This ambiguity is not a bug you can fix in the network. It is a permanent property of distributed systems, and idempotency is how well-designed APIs live with it.

The definition, without the jargon

An operation is idempotent if doing it once or doing it many times leaves the system in the same state. Setting a user’s city to “Pune” is idempotent: send it three times and the city is still Pune. Adding ₹500 to a wallet is not: send it three times and the wallet has ₹1,500 more.

Notice the definition is about the state on the server, not about the response. A second DELETE of the same resource might return 404 instead of 204, and the operation is still idempotent because the resource is gone either way.

What HTTP promises, method by method

The HTTP specification (RFC 9110) classifies methods by two properties. Safe methods should not change server state at all. Idempotent methods may change state, but repeating them has no further effect.

MethodSafeIdempotentTypical use
GET, HEADYesYesRead a resource
PUTNoYesReplace a resource with the given representation
DELETENoYesRemove a resource
POSTNoNoCreate something, or trigger an action
PATCHNoNot guaranteedApply a partial change

These are promises the API designer makes, not things HTTP enforces. A GET handler that increments a counter, or a PUT handler that appends to a list, breaks the contract, and clients, proxies and libraries that trust the contract will behave badly.

PUT versus PATCH

PUT means “make the resource look exactly like this”. You send the complete representation. If a profile has name, email and city, and you PUT only name and city, a strict implementation should clear the email. Because the outcome depends only on what you sent, repeating it changes nothing.

PATCH means “apply these changes”. You send only what changes. Whether that is idempotent depends on the kind of change. A patch that says “set city to Pune” is idempotent in practice. A patch that says “increase quantity by 1” or “append this item to the tags list” is not. JSON Patch, a common format, even has operations like add on arrays that insert a new element each time. So the honest statement is: PUT is idempotent by definition; PATCH can be, if you design the patch operations that way.

A practical consequence: HTTP clients and gateways often retry idempotent methods automatically on connection errors, but they should not retry POST or PATCH without help from the application.

Making POST safe to retry with idempotency keys

Creating a payment is naturally a POST, and naturally not idempotent. The widely used fix, popularised by payment providers such as Stripe, is the idempotency key. The flow looks like this:

  1. Before the first attempt, the client generates a unique key, typically a UUID, for this specific intent to pay. It stores the key with the pending order.
  2. The client sends the key in a header, commonly named Idempotency-Key, with the request.
  3. The server tries to insert the key into a table with a unique constraint, together with a “processing” status and a hash of the request body. If the insert succeeds, this is the first time it has seen the request, so it proceeds.
  4. When processing finishes, the server stores the final response (status code and body) against the key.
  5. If a retry arrives with the same key, the server returns the stored response instead of charging again. If the original is still processing, it returns a conflict or asks the client to retry later. If the same key arrives with a different body, it rejects the request, because the client has made a mistake.

Two details make or break this design. First, the key must be created once per user intent and reused on every retry. If the app generates a fresh key for each attempt, the whole mechanism does nothing. Second, the check must be atomic. Reading “does this key exist?” and then inserting it in a separate step lets two simultaneous retries both see “no” and both charge. A unique database constraint, or an atomic set-if-absent in a store like Redis, closes that gap.

The downstream problem

Your endpoint being idempotent is not enough if it calls a payment gateway that is not. If your server crashes after the gateway charged the card but before you recorded success, the retry will call the gateway again. The fix is to pass an idempotency key, or a stable merchant reference such as your order ID, through to the gateway as well, so the gateway can recognise the duplicate. Most Indian and international payment gateways support a merchant order reference for this purpose, though exact behaviour varies by provider, so check the documentation.

Where the gateway cannot deduplicate, you need reconciliation: a background job that asks the gateway for the status of any payment left in “processing” and settles it one way or the other. Idempotency reduces duplicates; reconciliation catches the ones that slip through.

Decisions you still have to make

  • How long to keep keys. Long enough to cover any realistic retry window. Twenty-four hours is a common choice; regulators or business rules may call for longer.
  • Scope. Keys should be scoped per user or per merchant, so one client’s key cannot collide with another’s.
  • Which failures to cache. A validation error (400) can be stored and replayed. A temporary failure such as a downstream timeout usually should not be, so a genuine retry gets a fresh chance.

Natural keys can sometimes replace generated ones. If the business rule is “one payment per order”, a unique constraint on order ID in the payments table gives you idempotency for free. Look for those first; add idempotency keys where no natural key exists.

Written by the RP Strativa Team. Figures in the examples are illustrative.

Leave a Reply

Trending