Idempotency

Definition

Idempotency means repeating the same logical operation produces no additional intended effect beyond the result of processing it once.

Overview

Contents Hide

Context and purpose
How it works
Practical checks and failure points
Related concepts
Further reading

Context and purpose

Idempotency does not make every operation reversible or safe to retry; the server must implement durable duplicate detection and clients must reuse the same key for the same intent. Idempotency is the property that repeating an equivalent operation under its defined key and scope does not create additional unintended effects. Clients must reuse the same key only for the same intent. Clients need bounded exponential backoff, jitter, retry limits, a deadline, and status lookup before assuming that a timed-out operation never executed. Assertions should verify final provider and business state, not only an HTTP status or locally mocked response. Idempotency must define the protected operation, client-supplied or derived key, uniqueness scope, request-equivalence rule, retention window, stored result, retry behavior, and conflict response. Systems should define key scope, retention, response replay, conflict behavior, and recovery after partial processing.

How it works

Idempotency makes repeated execution of one logical request safe by ensuring that retries do not trigger additional financial effects. A service typically associates a client-generated key with an operation identity and previously recorded result.

Practical checks and failure points

Scope the key to account and operation, compare meaningful request parameters, retain results for a documented window and handle concurrent requests atomically.

Idempotency Conflict · Idempotency Window

Example

A checkout POST times out after creating an invoice. Retrying with the same key should retrieve the existing invoice instead of issuing two.

Comparison

Idempotency is different from deduplicating webhooks, although both prevent repeated effects.

Key Takeaway