Idempotency Key

An idempotency key must be globally unique for each distinct operation attempt. The client generates a UUID or similar high-entropy token and sends it in the Idempotency-Key header. The server uses this key as a mutex lock to deduplicate requests. If the same key is received again, the server returns the cached response of the original operation rather than re-executing it. This shifts the burden of safe retries from the business logic to the infrastructure layer.

Idempotency keys are not stored indefinitely. Servers maintain a key-to-response mapping in a high-speed cache with a strict Time-to-Live (TTL), typically 24 hours. After expiration, a replayed key is treated as a new request. This prevents unbounded storage growth. The TTL must be communicated to clients so they understand the retry window. For financial transactions, keys may be persisted permanently in an append-only ledger for auditability.

The core mechanism relies on an atomic compare-and-swap operation. When a request arrives:

• Step 1: The server attempts to insert the key into the database with a 'PROCESSING' status.
• Step 2: If the insert succeeds, the operation executes.
• Step 3: If the insert fails due to a uniqueness constraint, the server fetches the existing result. This prevents the race condition where two concurrent retries both see no existing key and both execute the operation.

An idempotency key guarantees safe retries at the transport level, but the underlying operation must still be logically idempotent. For example, a 'create user' endpoint with an idempotency key prevents duplicate users on retry. However, a 'send email' endpoint may still send the email during the original request and fail to return a response. The retry with the same key will return the cached 200 OK, but the email was already sent. This is a post-commit failure scenario that requires out-of-band reconciliation.

Clients must implement exponential backoff with jitter when retrying requests with the same idempotency key. A typical strategy:

• Retry 1: Wait 1s
• Retry 2: Wait 2s
• Retry 3: Wait 4s
• Retry 4: Wait 8s (max) The client must reuse the exact same key for each retry. Generating a new key on each attempt defeats the purpose and creates duplicate operations. SDKs like Stripe's automatically handle this key lifecycle.

Idempotency keys operate at the application layer, distinct from network-level retries. A complete safety architecture layers:

• TCP retransmission: Handles packet loss.
• HTTP retry with idempotency key: Handles connection resets and 5xx errors.
• Saga pattern: Handles multi-step transactional rollbacks. The idempotency key ensures that an HTTP POST that succeeded but timed out is not re-processed. The server returns the original result from cache, making the retry transparent.