The Idempotency-Key HTTP header field (IETF draft) lets clients safely retry non-idempotent requests without causing duplicate processing. Servers use the key to detect and de-duplicate repeated operations, a common pattern in payment and write APIs.
Idempotency-Key
Idempotency-Key is an HTTP header field, defined in an IETF HTTP API Working Group draft, that lets a client attach a unique, client-generated token to a request so the server can guarantee the operation runs at most once. When a network fails mid-request and the client retries, the server recognizes the repeated key and returns the original result instead of charging a card, placing an order, or creating a record twice.
- A client-generated token - The caller mints a unique key (often a UUID) and sends it with the request, so the caller owns the identity of the operation.
- At-most-once semantics - The server stores the key and its outcome, then short-circuits any later request carrying the same key.
- Safe retries over unreliable networks - It turns a dangerous “did that POST actually go through?” into a safe replay.
- A defined fingerprint and expiry window - The draft describes how servers scope, match, and eventually forget keys.
This pattern is load-bearing in payment and write-heavy APIs — Stripe, PayPal, and countless billing systems require or recommend an idempotency key on every POST — because duplicate charges and duplicate orders are among the most damaging bugs an API can ship. As agents begin driving APIs autonomously and retrying on their own, an explicit idempotency contract becomes even more important: it is the difference between a resilient integration and one that quietly double-bills when the network hiccups.
