Idempotency-Key

Idempotency & Reliability de facto — unregistered response 4 spellings

A network timeout does not tell you whether the work happened. Idempotency-Key is the answer: the client generates a unique key, sends it with a mutating request, and the server promises that a second request carrying the same key returns the first response rather than doing the work twice.

It came out of payments, because that is where the cost of getting it wrong is a duplicate charge and a chargeback. It is still mostly a payments header. Across the catalog it is declared by roughly 127 providers under this spelling and another 45 as x-idempotency-key — against tens of thousands of APIs that accept POSTs and offer callers no safe way to retry them.

For an autonomous agent this is not a nicety. An agent that cannot distinguish “the request failed” from “the response was lost” either retries and risks duplicating, or does not retry and stalls. There is no third option the client can construct on its own.

The registry

Not registered with IANA. It is a de facto or vendor field — real, widely used, and governed by nothing but convention.

In the catalog

Declared by 127 providers across 4,915 published specification files in the API Evangelist catalog, where it appears as a response header — sent by the server.

It is spelled 4 different ways across those contracts — Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY, Idempotency-key. HTTP field names are case-insensitive (RFC 9110, §5.1), so every one of these is the same header. They are not the same string, which is why generated clients disagree about it.

Using it

Accept it on every non-idempotent operation — POST, and any PATCH that is not naturally idempotent. Scope stored keys to the authenticated caller, keep them for at least 24 hours, and return the original response on replay rather than a 409. State the retention window in your contract; a key with an undocumented lifetime is a key a client cannot reason about.

Spell it Idempotency-Key, matching the IETF draft. x-idempotency-key is the UK Open Banking spelling and is mandated there; everywhere else it is fragmentation.