# Idempotency

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

- Type: principle
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-24
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/idempotency/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/idempotency/#visualization-idempotency>)

## Sources

1. [RFC 9110: HTTP Semantics](<https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods>) — Internet Engineering Task Force · Internet standard
2. [Making Retries Safe with Idempotent APIs](<https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/>) — Amazon Web Services · Institutional engineering guidance

## Related topics

- [Retry](<https://wiki.soroush.uk/topic/retry/>)
- [Message Queue](<https://wiki.soroush.uk/topic/message-queue/>)
- [Webhook](<https://wiki.soroush.uk/topic/webhook/>)
