How can an idempotency key prevent duplicate API operations?

That is the uncertain-response problem: the server may have received and processed the request even though your client did not receive the reply. Retrying without a safeguard could create a second order.

For an API that supports idempotency keys, the client assigns a unique key to the intended operation and sends it with the request. If the response is lost, the client retries the same operation using the same key. The server can recognize the repeat and avoid performing the operation again, responding as though it had already done so. [S1]

Think of the key as identifying one operation—not as a general label for every order your application makes. A new order needs a new key; a retry of that same order reuses its key.

Assume an imaginary API documents idempotency support for order creation. The exact request syntax below is a placeholder, not a prescribed header name or valid API call:

1. Your application decides to create one order and generates a fresh key, such as [unique key for this order].
2. It sends the order request with that key.
3. If it receives a clear response, it handles that response normally and keeps the key associated with the operation as its design requires.
4. If the response is lost or times out, it retries the same intended operation using the same key.
5. If the customer starts a separate order, the application generates a different key.

The important distinction is “same operation, same key; new operation, new key.” The key does not by itself tell your client whether the first request succeeded. It helps a supporting server recognize a repeated request; the API defines what response a duplicate receives. [S1]

No universal format or retention period is established by this pattern. The key’s format, requirements, supported endpoints, and expiry are defined by the individual API. MDN describes the Idempotency-Key header as experimental and non-standard, so do not assume its name or behavior works everywhere. [S1]

Check the documentation for:

1. Whether the specific endpoint supports keys at all, and how to supply one.
2. What makes a key valid, including any documented format, length, or scope restrictions.
3. How long the server retains keys and what to expect if you retry after that period.
4. What happens when the same key is sent again, including whether the response reflects the earlier operation.
5. Any documented requirements for requests that reuse a key.

If details are absent, ask the API provider or treat the behavior as unknown rather than inventing a rule.

Create and store the key at the point your application commits to one operation—not each time a network attempt begins. Keep it attached to that operation through retries, and create a fresh key for a genuinely new operation. Track the API’s documented expiry if it provides one. Because expiry and duplicate behavior are API-defined, do not assume an old key will continue preventing a duplicate after its retention period. [S1]

For the example order, your internal record could be:

operation: create this order key: [unique key assigned to this order] attempts: initial request, then retries with the same key new order: assign a different key

If the response remains uncertain and the documented retry window has passed—or the API gives no clear guidance—pause automatic retries. Consult the API’s documented way to check operation status or ask its provider for guidance. An idempotency key is a retry aid, not proof that an operation succeeded, and APIs do not have one universal expiry or behavior.