Idempotency Header

Overview

An Idempotency Header is an HTTP request header that carries a client-generated key used by a server to recognize retries of the same intended operation. Configuration changes to Idempotency Header should be versioned and tested under burst, timeout, dependency failure, and restart conditions.

The main risks include key reuse across different operations, keys exposed in logs, collisions, inconsistent behavior across endpoints, and premature record expiry. The header transports the key; the server still needs a defined scope, durable record, request comparison rule, and result-replay behavior to provide idempotency.

In production, teams should define ownership and apply high-entropy keys, documented header name, tenant and endpoint scoping, payload fingerprinting, secure logging, and explicit retention. It is especially important for non-idempotent payment actions such as invoice creation, refund creation, or payout submission. For Idempotency Header, a missing response should remain uncertain until status lookup or reconciliation confirms whether the original operation executed.

Useful measures include header adoption rate, duplicate-prevention count, key conflict rate, and idempotency lookup latency. Idempotency Header is closely connected to Idempotent Request, Idempotency Record, and Idempotency Scope. The Idempotency Header implementation should bound attempts, preserve the original operation identity, and stop before retries amplify a dependency failure.

Manual intervention for Idempotency Header should begin only after automated status checks cannot determine a safe final outcome. The Idempotency Header policy should define which failures are retryable, how long the decision remains valid, and how duplicate effects are prevented.

Operational review of Idempotency Header should separate successful recovery from repeated attempts that only increase latency or load.