Blog

Idempotency Keys: How to Make "Retry This" Actually Safe

September 6, 2026Xerat023 min read
Share
Idempotency Keys: How to Make "Retry This" Actually Safe

A client sends a request, doesn't get a response (timeout, dropped connection, browser tab closed and reopened), and has no way to know: did the server actually process it, or not? The obvious fix — "just retry" — is only safe if retrying can't create the thing twice. For a GET, that's free: reading something twice does nothing extra. For a POST that charges a card or creates an order, retrying blindly risks charging the customer twice or creating two identical orders from one intended action.

What an idempotency key actually is

An idempotency key is a unique value the client generates and attaches to a request (commonly as an Idempotency-Key header), that the server uses to recognize "I've seen this exact request before, and it succeeded — here's the same result I gave you last time, don't do the work again." Stripe's API is the most widely cited real-world example of this pattern in production: attach the same idempotency key to a retried charge request, and Stripe returns the original charge's result instead of creating a second one, even if the first request's response never made it back to the client.

The key insight is that the client, not the server, decides what counts as "the same request" — because only the client knows whether a given API call represents one real-world intent (charge this customer once) or a second, deliberate action (charge them again for a different reason). A server can't infer that from the request body alone.

What the server has to actually do with it

Supporting this properly requires more than just deduplicating by key — a few specific things have to be true:

  • The key needs to be stored alongside the result of the first successful request, not just a flag that "this key was used," so a retry gets back the actual original response (same order id, same status), not a generic "already processed" error that leaves the client unsure what actually happened.
  • A key needs a reasonable expiration. Storing every idempotency key forever isn't practical; a window of 24 hours (a common choice) balances "long enough to cover any realistic retry" against "doesn't grow unbounded."
  • The same key with a different request body should be treated as an error, not silently processed as if it were the original request — otherwise a client bug that accidentally reuses a key across two genuinely different requests would silently corrupt one of them.
  • Concurrent requests with the same key (a double-click, or two tabs both retrying) need to not both slip through and create two records before either finishes — this usually means the server has to briefly lock on the key while the first request is in flight.

Why this matters more for POST than for PUT

This connects directly to a distinction worth internalizing on its own: PUT is conventionally idempotent by design (calling it twice with the same body produces the same end state), while POST conventionally is not (calling it twice creates two things). Idempotency keys are the mechanism that lets you get PUT-like safety on an endpoint that has to stay a POST because it's genuinely creating something new each first time, just not on a retry of the same attempt.

Testing this without risking a real double-charge

The failure mode you're actually trying to prevent — two charges from one user action — is exactly the kind of thing you don't want to discover by testing against a real payment provider's test mode with a flaky network simulated by unplugging your laptop mid-request. A mock endpoint that behaves like a real idempotent POST — same key returns the same stored response, a reused key with a different body returns an error — lets you confirm your client's retry logic actually sends the same key on retry (a surprisingly common bug: generating a new key on every retry attempt defeats the whole mechanism) using stateful routes to hold the first response against the key, without ever touching a real payment or messaging account.

X

Xerat02

Building MockBase.