principleEngineering & architecture

Idempotency

The property that repeating the same operation has the same intended effect as performing it once.

Download Markdown (.md)

01What it means

Idempotency means that applying an operation multiple times produces the same intended server state as applying it once. In HTTP, some methods have idempotent semantics by definition; application commands can also be made idempotent by recognizing a stable request key and returning the previously recorded outcome. Responses may differ while the intended effect remains unchanged.[1][2]

Duplicate-safe command handling The same logical request reuses one recorded outcome
  1. New keyAtomically record request identity
  2. ProcessingOne operation owns the effect
  3. CompletedPersist resulting outcome
  4. Repeated keyReturn recorded result

Mismatched input is rejected; matching input does not repeat the effect

Responses may differ, but the intended server state must match applying the operation once.

02Why it matters

Networks fail at ambiguous moments: a client may not know whether a timed-out request took effect. Idempotency lets clients retry important operations such as payments, order creation, and message handling without duplicating their business effects.

03When to use it

Design for idempotency wherever retries or duplicate delivery are possible and duplicate effects would be harmful. It is especially valuable for creation commands, payments, webhooks, and queue consumers. Purely transient reads or operations whose repetition is intentionally cumulative need different semantics.

04How it works

  1. Define which inputs identify the same logical operation and what outcome should be stable.
  2. Have the caller provide a unique idempotency key scoped to the operation and actor.
  3. Atomically record the key, request identity, processing state, and resulting outcome.
  4. On a repeat, reject mismatched input or return the recorded result without repeating the effect.
  5. Choose retention and cleanup rules that cover the realistic retry window.
  6. Test concurrent duplicates, crashes during processing, and downstream side effects.

05A practical example

Example

A checkout client sends a payment request with an idempotency key and loses the response. Its retry uses the same key, so the service returns the original charge result rather than charging the card twice.

06Where it breaks

Idempotency requires durable state, careful atomicity, and a defined key scope and lifetime. It cannot automatically undo non-idempotent downstream effects, and reusing a key with changed parameters creates ambiguity that the service must reject.

Common mistakes

  • Treating identical response bodies as the definition instead of identical intended effects.
  • Checking for a key and performing the effect in separate race-prone operations.
  • Generating a new key for every retry of the same logical request.
  • Expiring records before delayed retries or duplicate messages can arrive.

07Sources

  1. RFC 9110: HTTP SemanticsInternet Engineering Task Force · Internet standardRFC 9110: HTTP Semantics
  2. Making Retries Safe with Idempotent APIsAmazon Web Services · Institutional engineering guidanceMaking Retries Safe with Idempotent APIs
View saved topics

Start typing to search titles, definitions, categories, and frameworks.