Skip to content

Idempotent API

Interface protocol — instantiates Request–Response Capability Provisioning

An interface that lets a client safely repeat a request: a duplicate carrying the same key returns the original result instead of executing the action a second time.

Networks lose responses, so a client often cannot tell whether its request landed — and blindly resending risks doing the action twice. Idempotent API removes that danger at the receiving end: it is an interface whose defining guarantee is that repeating a request has the same effect as making it once. Each mutating call carries a client-supplied idempotency key that fingerprints the intended operation; the provider records the outcome against that key, so a replay is recognized and answered with the original result rather than executed again. Where a retry policy lives on the client and decides when to repeat, the idempotent API lives on the provider and makes the repeat safe to receive.

Example

A shopper taps "Pay $40" in a mobile app; the charge request goes out with an idempotency key like chg_9f2a…, and then the network drops the server's reply. The app has no way to know whether the money moved. Because the charge endpoint is idempotent, the app can simply resend the same request with the same key. The provider sees the fingerprint, finds a completed charge already recorded against it, and returns the original success response — the customer is charged exactly once, no matter how many times the uncertain request is retried. The same key sent from a fresh app launch after a crash still resolves to the one charge. The guarantee is a property of the request-to-response mapping, not of the client's luck with the network.

How it works

What distinguishes an idempotent API from an ordinary endpoint is dedup anchored on a client-declared key:

  • Require a fingerprint in the request — the contract mandates a caller-supplied idempotency key that uniquely identifies the intended operation.
  • Check a completion record — on receipt, the provider looks up whether that fingerprint has been seen.
  • First time, execute and record — perform the action and store its outcome against the key.
  • Duplicate, replay — skip execution and return the stored response or error verbatim.

Because the key is declared by the client, the guarantee survives retries, timeouts, and even client restarts — anywhere the same intent might be sent twice.

Tuning parameters

  • Key scope and retention — how long completion records are kept and how broadly a key must be unique. Longer retention catches late duplicates; it costs storage.
  • Fingerprint source — a client-supplied key versus a server-derived hash of request content. Client keys distinguish a deliberate repeat from a coincidentally-identical new request; content hashes need no client cooperation but cannot tell the two apart.
  • Duplicate-response fidelity — replay the exact original response versus a bare "already processed" acknowledgement. Exact replay is transparent to the client but means storing the full response.
  • Same-key-different-payload handling — reject the conflict versus ignore it. Rejecting surfaces client bugs; ignoring is lenient.
  • Idempotency window — at-most-once forever per key versus time-boxed. Bounds storage against the risk of an out-of-window duplicate slipping through.

When it helps, and when it misleads

Its strength is that it makes the network's inherent uncertainty safe: clients and retry logic can repeat freely without double-execution, so at-least-once delivery becomes effectively once. The failure modes hide in the seams. Idempotency covers only what the completion record captures — a side effect that escapes the key (an email already sent, a downstream call already fired) can still happen twice. And retention set too short lets a late duplicate fall outside the window and execute again. The classic misuse is bolting an idempotency key onto an operation whose downstream effects the record does not actually own: the API cheerfully answers "already done" while a second side effect fires anyway. The discipline is to define idempotency at the boundary that owns all the effects, in the spirit of the standard notion of an idempotent method[1].

How it implements the components

Idempotent API fills the request/response de-duplication subset of the archetype's machinery — the components that govern the shape and repeatability of a call:

  • request_contract — it defines the well-formed request, including the required idempotency key every mutating call must carry.
  • request_fingerprint — the idempotency key is the fingerprint that tells a new request from a replay; this is the mechanism's signature component.
  • response_and_error_contract — it specifies that a duplicate resolves to the recorded original response or error, not a fresh execution.

It does not decide when a client should retry or back off — that is Safe Retry Protocol, which depends on this guarantee; it does not authenticate the caller (Authentication Broker) or advertise the endpoint (Central Registry).

  • Instantiates: Request–Response Capability Provisioning — it makes the response-and-error side of the contract robust to the retries that a shared, unreliable channel inevitably produces.
  • Sibling mechanisms: Safe Retry Protocol · API or RPC Endpoint · Authentication Broker · Central Registry · Autoscaling Worker Pool · Parallel Server Activation · Rate Limit with Burst Allowance · Weighted Fair Queue · Service-Level Agreement · Service-Level Monitor · Intake Portal · Shared Service Desk · Ticketing System · Cache or Read Replica

Notes

Idempotency and retries are a matched pair authored from opposite ends. An idempotent API is what makes a Safe Retry Protocol safe; a retry protocol is what makes idempotency useful. Neither is complete alone — one guarantees a repeat is harmless, the other decides when to repeat.

References

[1] Idempotency as defined for HTTP methods (RFC 9110): a method is idempotent if the intended effect of several identical requests equals that of a single one — PUT and DELETE are, POST is not. A client-supplied idempotency key extends that guarantee to operations that would otherwise be unsafe to repeat. ↩