Idempotent Request

Idempotency is a core property of specific HTTP methods defined by the protocol specification. Safe methods like GET, HEAD, and OPTIONS are inherently idempotent as they only retrieve data. Idempotent methods include PUT and DELETE, where multiple identical requests should leave the server in the same state as a single request. For example, calling DELETE /resource/123 twice results in a 404 Not Found on the second attempt, which is the same final state as after the first successful deletion. The POST method is not idempotent by default, as it typically creates a new resource each time it is called.

For non-idempotent operations like POST or PATCH, a common pattern is to use a client-generated idempotency key. This is a unique token (e.g., a UUID) sent in a request header (e.g., Idempotency-Key: <key>). The server stores the key with the result of the first request. Subsequent retries with the same key return the stored response without re-executing the operation. This mechanism is critical for:

• Financial transactions to prevent duplicate charges.
• Order processing to avoid creating duplicate orders from retried network calls.
• Resource creation APIs where POST must be safely retryable.

The fundamental guarantee of an idempotent request is state equivalence. Executing the operation N times (where N > 0) must produce the same server-side state as executing it exactly once. This does not necessarily mean identical responses. For instance:

• The first PUT /item/1 with data {"status":"active"} may return 200 OK.
• An identical retry may also return 200 OK or a 409 Conflict if a race condition occurred, but the resource's final status will still be "active".
• The second DELETE /item/1 returns 404 Not Found, which is a different HTTP response than the first 204 No Content, but the server state (resource absent) is identical.

Idempotent requests must have deterministic and localized side effects. Any change to data, logs, or external systems triggered by the request must be the same regardless of how many times it is processed. This requires the server's request handler to be a pure function of the request parameters for a given resource state. Key implementation patterns include:

• Using last-write-wins semantics with timestamps or versions for PUT operations.
• Implementing compare-and-swap logic to ensure updates are applied only if the resource is in an expected state.
• Avoiding side effects like sending a notification email or incrementing a counter within the idempotent operation's transaction; these should be moved to a separate, idempotent process.

It is crucial to distinguish between idempotent and safe HTTP methods.

• Safe methods (GET, HEAD, OPTIONS, TRACE) promise no state modification. All safe methods are idempotent.
• Idempotent methods (PUT, DELETE) may change server state, but doing so repeatedly yields no additional change. They are not safe. This distinction dictates client behavior: browsers can safely retry safe methods automatically. For idempotent but unsafe methods, automated retries are permissible from a state integrity perspective, but may still have other consequences (like logging).

For custom API actions or RPC-style endpoints (e.g., POST /api/transferFunds), idempotency must be explicitly engineered. Beyond using idempotency keys, common strategies include:

• Idempotent Receivers: Designing the business logic to check for a previously completed transaction using a unique business key (e.g., a transfer reference ID) before proceeding.
• Idempotent Workflows: Structuring the operation as a series of idempotent steps, often using a state machine where transitioning to a final state is idempotent.
• Compensating Transactions: For complex operations, implementing a rollback or compensating action that is also idempotent, allowing the entire flow to be safely retried. This pattern is central to the Saga pattern in distributed transactions.

Idempotency is the broader mathematical and system design property that an operation can be applied multiple times without changing the result beyond the initial application. An idempotent request is the specific implementation of this property for HTTP. This property is critical for safe automatic retries in distributed systems, as it guarantees that duplicate calls do not cause unintended side effects like double-charging a payment or creating duplicate database records.

Exponential backoff is a retry algorithm that increases the wait time between consecutive retry attempts exponentially. It is commonly paired with idempotent requests to handle transient errors (e.g., network timeouts, temporary service unavailability).

• Mechanism: Delay = base_delay * (backoff_factor ^ retry_attempt).
• Purpose: Prevents retry storms that could overwhelm a recovering service.
• Use with Idempotency: Because the requests are idempotent, these delayed retries are safe and will not cause duplicate mutations if the original request eventually succeeded.

An idempotency key is a client-generated unique identifier (often a UUID) sent with a non-idempotent API request (like POST) to make it idempotent. The server uses this key to recognize duplicate requests.

• How it works: The server stores the key and the response of the first request. Subsequent requests with the same key return the stored response without re-executing the operation.
• Example: Payment APIs like Stripe use idempotency keys to prevent duplicate charges from retried requests.
• Critical for Agents: AI agents must generate and manage these keys to ensure safe retries of state-changing operations.

In HTTP, certain methods are defined as safe, meaning they are intended only for information retrieval and should not change server state. By definition, safe methods are also idempotent.

• GET: Retrieves a representation of a resource. Multiple identical GET requests return the same data.
• HEAD: Identical to GET but returns only headers, no body.
• OPTIONS: Describes the communication options for the target resource.
• Implication for Agents: AI agents can safely retry these methods without any risk of side effects, making them ideal for data-fetching operations in a retry loop.

The HTTP PUT and DELETE methods are defined as idempotent but not safe.

• PUT: Replaces a resource at a known URI. Calling PUT /users/123 with the same data ten times has the same effect as once—the user is updated to that state.
• DELETE: Removes a resource. DELETE /users/123 returns a 404 after the first successful call, but the server state (user deleted) remains unchanged by subsequent calls.
• Design Principle: This idempotency allows clients and agents to retry these operations confidently during network failures or when a response is lost.

The HTTP POST method is not idempotent by default. It is used to create a new resource where the server typically assigns the ID.

• The Problem: Two identical POST requests usually create two separate resources.
• The Solution: To make POST requests safe for retries, APIs implement the idempotency key pattern (see related card).
• Agent Design Consideration: AI agents must be aware of which endpoints are idempotent and which require a key. Tool-calling frameworks should provide mechanisms to automatically attach idempotency keys to non-idempotent operations defined in an API schema.