Idempotency (Software)

Reference entry · last updated October 19, 2026

Idempotency is the property of an operation whose repeated application has the same intended effect as a single application. In HTTP, the definition concerns the requested effect on the server; responses may differ between attempts.[1]

First principles and definitions

An operation can change state while remaining idempotent. HTTP distinguishes this property from safety: a safe method requests essentially read-only behavior. An idempotent method may request a change, provided repetition has the same intended effect.[1]

The following examples are illustrative. Each assumes the same target and inputs, no intervening writer, and only the stated effect.

Operation	Repeated effect	Idempotent?
Set an account's status to `active`	Status remains `active`.	Yes
Increase a counter by one	Each repetition increases the counter again.	No
Remove a named item from a set	The item remains absent.	Yes
Toggle a Boolean value	Each repetition reverses the previous value.	No

HTTP methods

RFC 9110 defines PUT, DELETE, and safe methods such as GET as idempotent. Logging each request or keeping revision history is permitted: the property applies to the requested effect. POST has no general idempotency guarantee, although a particular API can supply one.[1]

PATCH is not inherently idempotent. Its specification allows idempotent uses and recommends conditional requests for patch formats that depend on a known resource version.[2]

Idempotent semantics allow a client to repeat a request after a connection fails before the response arrives. RFC 9110 cautions against automatically retrying a non-idempotent request without evidence that its semantics are idempotent or that the original was never applied.[1]

Retries and idempotency keys

A timeout can leave a client uncertain whether a service created a resource. Repeating an unprotected creation request can create another resource. Amazon's Builders' Library describes using a caller-provided request identifier to distinguish retries from separate intentions. Matching parameters alone are insufficient: a caller may intend to create two identical resources.[3]

In an illustrative order API, a client assigns key order-attempt-42 to one intended purchase and keeps that key for its retries. A separate purchase receives a new key, even if the basket is identical. The service's documented contract determines which requests count as duplicates.

Amazon EC2 documents that a successful request repeated with the same client token and parameters performs no further action. Changing parameters can produce IdempotentParameterMismatch, subject to its Region and Availability Zone rules.[4]

Atomic deduplication

Recording a request identifier and making the associated state changes must form an atomic operation in the Builders' Library design. Otherwise, a service can record the identifier without creating the resource, or create the resource without recording the identifier.[3]

As an illustrative database design, a unique constraint on the caller and key can arbitrate simultaneous duplicates. The request record and order write commit in one transaction. A second request uses the committed record, or receives a defined in-progress outcome. An email or payment outside that transaction requires its own failure-handling contract; the database transaction alone does not cover it.

Scope and failure limits

Token scope is part of the API contract. EC2 distinguishes regional and zonal idempotency; the same token can create resources in different Regions or, for zonal operations, different Availability Zones.[4]

Late retries need a defined policy. The Builders' Library describes EC2 preserving the original request's meaning even after the created instance has been terminated.[3]

Stripe's API v1 documents that keys can be pruned after at least 24 hours. Reusing a pruned key starts a new request. It saves the first executed request's status and body, including a 500 response, and returns that saved result on a retry.[5]

Idempotency alone does not establish eventual success or an end-to-end exactly-once guarantee. In the illustrative order design, deduplication covers only the stored key and protected writes. Deleting that record removes the evidence used to recognize a retry.

References

^ R. Fielding, M. Nottingham, and J. Reschke, RFC 9110: HTTP Semantics, §§9.2.1–9.2.2, June 2022.
^ L. Dusseault and J. Snell, RFC 5789: PATCH Method for HTTP, §2, March 2010.
^ Malcolm Featonby, Making retries safe with idempotent APIs, Amazon Builders' Library.
^ Amazon Web Services, Ensuring idempotency in Amazon EC2 API requests, Amazon EC2 Developer Guide.
^ Stripe, Idempotent requests, API v1 behavior.