Design patterns and optimization · Intermediate

Idempotent requests: retry without duplicating effects

Use a lost order response to reason about idempotency keys, atomic records, and the retention window.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. A timeout leaves the outcome uncertain
  2. Identify the operation rather than just the payload
  3. Make recording and effect creation atomic
  4. Define states, retention, and authorization
  5. Respect the semantics behind the method name
  6. Ask Logeia about this articleCheck your understanding

A timeout leaves the outcome uncertain

A client sends an order and loses the connection before receiving the response. The server may already have committed the order. Sending the request again as an unrelated operation can create a duplicate. Idempotence means that repeating the same operation has the same intended effect as performing it once. It does not require every response body or status code to be identical, and it depends on a clear definition of the operation.

Identify the operation rather than just the payload

Create an operation key when the user starts the action, and reuse that key for retries. Scope it to the authenticated principal and the operation type. If the same key arrives with different order details, reject the conflict instead of silently reusing an unrelated result. Hashing the payload alone is insufficient: the user may intentionally buy the same product twice, and those two actions need different operation identities.

Make recording and effect creation atomic

If an order is stored before its deduplication record, a failure in between can leave an order that a retry cannot recognize. When possible, create the order and record its key in one database transaction, protected by an appropriate unique constraint. Concurrent duplicate requests must also compete for the same identity. An external payment system cannot usually participate in that local transaction, so coordinate its own idempotency mechanism or a recoverable state machine.

Define states, retention, and authorization

Decide what happens while an operation is still running and after it has completed. A completed request may return a stored result; an in-progress duplicate may wait or receive an explicit progress response. A key deleted after twenty-four hours cannot prevent duplicates outside that window. Match retention to the retry contract. Recheck authorization when serving a result: possession of an operation key is not permission to read another user’s transaction.

Respect the semantics behind the method name

HTTP defines the intended semantics of methods such as PUT and DELETE as idempotent, but an implementation must honor those semantics. A POST endpoint can also offer an application-level idempotency contract. Conversely, naming an endpoint PUT does not automatically deduplicate hidden billing or notification effects. Review the entire operation, including external side effects and recovery behavior, before deciding that an uncertain request can safely be retried.

Reading and practice are recorded separately in this browser, for each language.

Learn this in order

Understand the systems behind the web · STEP 16

Choose a learning path