Idempotency

Idempotency is the property of an operation that has the same effect whether it runs once or several times. Setting a value to 5 is idempotent. Adding 5 to a value is not. In distributed systems it is what makes retries safe, because a client often cannot tell whether a timed out request actually succeeded.

How it works

The common pattern is an idempotency key. The client sends a unique key with the request, for example an Idempotency-Key header on POST /payments. The server stores the key with the result. If the same key arrives again, it returns the stored result instead of doing the work twice. A client that times out after 30 seconds and retries a 50 dollar charge is charged 50 dollars once, not 100. HTTP defines GET, PUT and DELETE as idempotent and POST as not.

Why it matters in production

Networks drop responses, consumers get redelivered messages and on-call engineers rerun jobs. Without idempotency, each of these becomes a duplicate order, email or payment. Idempotent handlers let teams use at-least-once delivery and aggressive retries without data damage.

See also

• Exactly-once semantics

• Exponential backoff

• Dead letter queue

• Rate limiting

On the One2N blog

• Disaster recovery for SREs: the practical playbook for RTO, RPO, and cutover

• How temporal versioning prevents configuration drift in stream processing

Further reading

• RFC 9110: idempotent methods