Idempotency Key

An idempotency key is a globally unique identifier (e.g., a UUID v4) generated by the client application before making an API request. This client-side generation is critical because it allows the server to identify the intent of a specific operation, regardless of network retries or client crashes. The key must be unique per distinct logical operation; reusing a key for a different request will return the cached result of the original request.

• Example: A payment service client generates idempotency-key: pay_550e8400-e29b-41d4-a716-446655440000 for a $100 transfer.
• Responsibility: The client is responsible for key uniqueness. The server's role is to validate, store, and enforce idempotency based on this key.

The server uses the idempotency key to enforce idempotent behavior through a request deduplication mechanism. Upon receiving a request, the server checks if the key exists in a persistent store (e.g., a database or distributed cache).

• First Request: If the key is new, the server processes the request, stores the key alongside the resultant response (status code, headers, body), and returns the response.
• Subsequent Request: If the key already exists, the server bypasses business logic execution and immediately returns the stored response from the first request.

This mechanism ensures the backend operation (e.g., charging a card, creating a database record) is executed exactly once, even if the identical request is received multiple times.

Idempotency keys are not permanent. They have a defined lifespan or time-to-live (TTL) after which they are purged from the server's cache. This scope is crucial for managing storage and ensuring keys can be safely reused after a long period.

• Typical Scope: Keys are often valid for 24-72 hours, aligning with the window for resolving most network or client-side issues.
• Post-Expiration: A request with an expired key is treated as a new, unique operation. This prevents the storage system from growing unbounded and allows for legitimate retries of the same logical operation (e.g., a monthly subscription charge) after a significant time has passed.

For idempotency to be reliable, the server's response to the first successful request must be deterministic and fully cacheable. The server stores the complete HTTP response—status code, headers, and body—associated with the idempotency key.

• Requirement: The underlying operation must produce the same output for the same input. Non-deterministic operations (e.g., "generate a new random ID") are not suitable for simple key-based idempotency.
• Replay: When a duplicate key is detected, the server replays the exact cached response. This includes success responses (e.g., 201 Created with a resource ID) and client error responses (e.g., 422 Unprocessable Entity). This prevents a failed request from being retried successfully if the initial failure was due to client error.

While related, idempotency is a semantic property of an operation, whereas request deduplication is an implementation mechanism. An idempotent operation (like GET or PUT) is inherently safe to repeat. A non-idempotent operation (like POST) is made safe via deduplication using an idempotency key.

• Key-Based Deduplication: This is the pattern used for POST requests to create resources. The key ensures the POST behaves like a single, atomic creation.
• Contrast with Idempotent Methods: HTTP methods like PUT and DELETE are defined as idempotent by specification; repeating them yields the same state. Idempotency keys add a client-controlled, request-scoped layer of deduplication on top of this.

In AI agent orchestration, idempotency keys are essential for integrating with external APIs within stateful workflows (e.g., Temporal workflows, Durable Functions). They prevent duplicate tool calls when an orchestration engine replays a workflow after a failure.

• Workflow Replay: Orchestrators often replay steps from a checkpoint. An idempotency key generated from the workflow ID and step sequence ensures the same external API (e.g., a payment processor) is not called multiple times.
• Saga Pattern Support: In a Saga, each compensating transaction should also use an idempotency key to ensure rollback operations are safe to retry. This is critical for achieving atomicity guarantees in distributed, long-running processes.

The Saga pattern is a design pattern for managing data consistency in distributed transactions by breaking them into a sequence of local transactions, each with a compensating action for rollback. Idempotency keys are essential for safely retrying individual saga steps.

• Compensating Transactions: Each step has a defined undo operation (e.g., CancelReservation).
• Orchestrated or Choreographed: Can be managed by a central orchestrator or through event exchange.
• Use Case - E-commerce Order: A saga might include: ReserveInventory → ChargeCard → ShipOrder. If ChargeCard fails, ReleaseInventory is executed.

Optimistic locking is a concurrency control method that allows multiple transactions to proceed without locking resources, detecting conflicts at commit time using a version number or timestamp. Idempotency keys can work alongside this pattern to handle retries of conflicting updates.

• Conflict Detection: Checks if the data has been modified since it was read.
• Version Numbers: Each record has a version that is incremented on update.
• Retry Logic: If a conflict is detected, the operation (with its idempotency key) can be retried with fresh data, preventing duplicate updates from the same logical request.

A circuit breaker is a resilience pattern that prevents an application from repeatedly attempting to execute an operation that is likely to fail, allowing time for the failing service to recover. It protects systems from cascading failures when calling idempotent or non-idempotent APIs.

• Three States: Closed (normal operation), Open (requests fail fast), Half-Open (testing recovery).
• Failure Threshold: Trips open after a defined number of consecutive failures.
• Combined with Idempotency: When the circuit is closed again, idempotency keys ensure safe retry of the original request.

Exponential backoff is a retry algorithm that progressively increases the waiting time between retry attempts, often used to handle transient failures (e.g., network timeouts, throttling) in distributed systems. It is a standard companion to idempotency keys for robust API calls.

• Algorithm: Wait time = base_interval * (2 ^ attempt_number).
• Jitter: Random variation is added to wait times to prevent thundering herds.
• Purpose: Gives overloaded or recovering backend services time to stabilize before a retry, which is safe due to the idempotency key preventing duplicate processing.

Event sourcing is an architectural pattern where state changes are stored as a sequence of immutable events, allowing the system state to be reconstructed by replaying those events. Idempotency keys are crucial for ensuring the same event is not applied multiple times during replay or from duplicate publishers.

• Immutable Log: The event log is the source of truth.
• State Derivation: Current state is computed by applying all events in sequence.
• Duplicate Prevention: Each event is assigned a unique idempotency key (often as an event ID). The system rejects any event with a key that has already been processed, maintaining correctness.