Product → API Products
API Idempotency
A property where repeating the same operation has the same effect as performing it once.
Where it fits
API Idempotency matters in HTTP APIs, distributed systems, payments, retries, queues, and any workflow where duplicate writes would be harmful. It helps systems behave safely when requests are repeated because of timeouts, client retries, network uncertainty, or message redelivery.
Mental model
An operation is idempotent when performing it multiple times has the same intended effect as performing it once. In APIs, idempotency is often implemented with request semantics and an Idempotency Key.
Example
Retrying DELETE /sessions/123 should leave the session deleted. Retrying a payment creation should not charge the customer twice if an Idempotency Key is used.
Subconcepts
A Safe Retry repeats an operation without duplicating or corrupting the intended result. A Duplicate Request is a repeated request that may come from a timeout, refresh, queue redelivery, or user action. An Idempotency Window is the period during which the server remembers keys and previous results.
Common mistakes
- Assuming every retry is safe.
- Ignoring network timeouts after the server may have already processed the request.
- Confusing idempotency with read-only behavior.
- Generating a fresh idempotency key for every retry instead of reusing the same key for the same logical operation.
Related concepts
HTTP methods, REST, Retry, Idempotency Key, message queues, request-response, transactions, and distributed systems.