When a POST request times out, the client can't tell whether the server acted on it. The IETF's draft for an Idempotency-Key header describes that case: the client "doesn't know if the resource was created or updated, or if the server even completed processing the request," and doesn't know whether it can safely retry (IETF draft). An idempotency key is the draft's answer: a unique value generated by the client, which the server uses to recognise later retries of the same request.

Why a retry is risky in the first place

HTTP has a formal idea of a request that's safe to repeat. RFC 9110 calls a method idempotent if the intended effect of multiple identical requests is the same as the effect of a single one, and it lists PUT, DELETE and the safe methods as idempotent (RFC 9110). The draft adds that POST and PATCH are not, which matters because the draft's own example is a client creating a resource with a POST.

The reason the distinction exists is retries. RFC 9110 says idempotent methods are singled out because a client can repeat the request automatically if the connection fails before it reads the response, knowing the repeat has the same intended effect even if the first attempt succeeded. For everything else, it says a client should not retry automatically unless it has some way to know the request is effectively idempotent or to detect that the original was never applied. The draft's header is aimed at those methods: its abstract says it "can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant."

The same section of RFC 9110 adds that the response might differ on a repeat, and that a server is free to log each request separately.

What the server does when the same key comes back

Stripe's API documentation describes the mechanism in concrete terms. Its docs say that when you create or update an object, you send a key, and if a connection error occurs you can repeat the request without risk of creating a second object or applying the update twice (Stripe docs). For its v1 API, Stripe saves the status code and body of the first request made with a given key, and retries with the same key return that saved response, including 500 errors. The v2 API works differently: retries don't repeat successful operations, and Stripe retries failed or partially failed work to completion where it can.

The key itself comes from the client. Stripe leaves the choice to you but suggests V4 UUIDs or another random string with enough entropy to avoid collisions, allows up to 255 characters, and says to avoid sensitive data such as email addresses as keys. It also compares the incoming parameters to the original request and returns an error if they differ, so a key can't be reused for a different request by accident. For v1, all POST requests accept keys, while sending one with a GET or DELETE has no effect because those are idempotent by definition.

The IETF draft lays out the same cases in more general terms. A first request is processed normally. A retry that arrives after the original completed should get a response consistent with the request having completed. A retry that arrives while the original is still being processed should get a 409 conflict, and reusing a key with a different payload should get a 422. A missing key on an operation that requires one should get a 400. Those are all "should" statements in an Internet-Draft, which the IETF's own status text calls a working document. As of 23 October 2026 the latest version is 08, dated 22 October 2026, and it expires on 25 April 2027.

Neither source describes your product. Stripe's behaviour applies to Stripe, and the draft says resources "MUST publish an idempotency-related specification" that "MUST include expiration related policy if applicable."

What to confirm before you describe it

Take a hypothetical customer, Northwind, whose developer asks, "If our system times out calling your create-order endpoint, can we retry without creating a duplicate?" If your product supports keys, a reply that stays within what you've confirmed is: "If you send the same key with the retry, our API recognises it as the same request. Let me confirm which endpoints accept a key and send you the doc." That promises the mechanism without promising coverage you haven't checked. It also separates the API's ability from the buyer's finished integration, the same line we drew in how to explain APIs to buyers.

Settle these from your product's documentation: which endpoints accept a key, whether the client supplies it or the product generates one, what a replay returns, what happens on a concurrent request or a changed payload, and how long a key is remembered.

Key lifetime is the point with a documented example. For its v1 API, Stripe says keys can be removed automatically once they're at least 24 hours old, and that a request reusing a pruned key is treated as a new request. Your own product's retention period is a separate number to look up.