Overview
This page is the atomic definition. The general-principles deep-dive lives at general-principles.
Definition
An idempotent operation produces the same observable state whether it is run once or many times with the same input. In HTTP, GET, PUT, and DELETE are defined as idempotent; POST is not. In database work, INSERT ... ON CONFLICT DO NOTHING is an idempotent insert. Idempotency is what makes retries safe in distributed systems: a client can replay a request after a timeout without fear of duplicate side effects, as long as it uses an idempotency key the server checks against a history table.
When it applies
Design API endpoints, background jobs, migrations, and event handlers to be idempotent. Required whenever the network can drop a response or a worker can crash mid-task.
Example
A payments API accepts an Idempotency-Key header; the server records the key with the response. A retried request with the same key returns the original response instead of charging the card again.
Related concepts
- general-principles - the broader principles that include idempotency.
- side-effect - non-idempotent operations are those whose side effects compound.
- immutable-data - immutable inputs make idempotency easier to reason about.
- http-status-codes - the HTTP method semantics that define idempotency.
- migrations - schema migrations must be idempotent to survive partial application.
Citing this term
See Idempotent (llmbestpractices.com/glossary/idempotent).