CONCEPT Cited by 1 source

Idempotent operations

Definition

An idempotent operation is one whose effect is the same whether executed once or many times with the same inputs. Idempotency is the enabling property for safe retries: without it, a retry after an ambiguous failure (timeout, connection drop) risks duplicating the side effect.

Zalando's timeouts post frames the retry-safety connection directly:

"If the operation being performed is idempotent, meaning that executing it multiple times has the same result as executing it once, retries are generally safe." (Source: sources/2023-07-25-zalando-all-you-need-to-know-about-timeouts)

Examples

Idempotent by nature: - GET /users/42 — reading a resource. - PUT /users/42 { "name": "Ada" } — full replacement of a resource with the same body. - DELETE /users/42 — second delete is a no-op. - SET key value in a KV store. - UPDATE users SET status='active' WHERE id=42 — the status is "active" after one write or ten.

Not naturally idempotent (see concepts/non-idempotent-operations): - POST /orders { ... } — each call may create a new order. - UPDATE counters SET n = n + 1 — each retry increments again. - Financial debits and transfers.

HTTP method semantics

HTTP verbs advertise intended idempotency to callers and caches:

Method	Intended idempotency
GET, HEAD, OPTIONS	Safe (idempotent + side-effect-free)
PUT, DELETE	Idempotent
POST	Not idempotent by default
PATCH	Depends on payload semantics

The advertised semantics are a contract, not a guarantee — application code is free to violate them, and many APIs have non-idempotent PUTs or effectively-idempotent POSTs. Callers should verify rather than assume.

Making a non-idempotent operation idempotent

The canonical mechanism is the Idempotency-Key header: the caller supplies a unique key with each logical operation; the server deduplicates by key and returns the original response on replay. Named references the Zalando post cites:

• Stripe — Idempotent Requests
• Amazon Builders' Library — Making retries safe with idempotent APIs

The load-bearing idea: server-side deduplication by caller-supplied key converts any write into an idempotent one from the caller's perspective.

The Zalando house-style caveat

Even when an operation appears idempotent, the Zalando post recommends confirming with the owner before enabling retries:

"Even if you think an operation is idempotent, if possible, ask the service owner whether it is a good idea to enable retries."

Reasons to ask: - Apparent idempotency may hold at the API boundary but not downstream (e.g. an idempotent endpoint that emits a non-idempotent event). - Side-effects like analytics, notifications, or audit log entries may duplicate even when the core state transition does not. - Retries may amplify load on a struggling service beyond the point a circuit breaker can catch.

Seen in

• sources/2023-07-25-zalando-all-you-need-to-know-about-timeouts — canonical framing as the determining property for retry-safety.

Related

• concepts/non-idempotent-operations — the complement; retries require additional safeguards.
• concepts/exponential-backoff-jitter — the retry- scheduling discipline once idempotency permits retries.
• patterns/retry-on-5xx-not-4xx — Zalando house-style retry policy that assumes idempotent (or idempotency-keyed) operations.
• patterns/idempotency-key-header — the contract that promotes non-idempotent writes to safely retryable ones.
• patterns/circuit-breaker — pairs with retry to avoid load amplification.