The Idempotency-Key header is back: what draft 08 asks of your API, and six tests to check it
The IETF draft that standardises the Idempotency-Key header expired in April. On 22 October 2026 the HTTP APIs working group published revision 08, which is valid until 25 April 2027. The changes are small, but the timing matters. More and more POST requests come from code that retries by itself: SDKs with automatic retries, queue workers, and AI agents that call the same tool again when a response is slow. Each of those retries can charge a card twice if the API doesn't recognise it as a repeat.
This post sums up what the draft asks of a server and turns each rule into a test you can point at your own endpoint. We ran the tests against the payments API on testingapis.com. It passed four of the six, and one of the two failures created a duplicate payment.
What the draft asks for
A client sends a unique value with a request that isn't idempotent, usually a POST or a PATCH. If the same request arrives again with the same key, the server returns the result of the first request instead of doing the work twice. That much is what Stripe and many others have done for years. The draft writes down the details:
| Situation | What the server should do |
|---|---|
| Key missing on an operation that requires one | 400, with a problem+json body titled "Idempotency-Key is missing" |
| Same key, same request, first one finished | Respond as if the request had completed. The draft doesn't fix a status code. |
| Same key, different request body | 422, titled "Idempotency-Key is already used" |
| Same key while the first request is still running | 409, titled "A request is outstanding for this Idempotency-Key" |
A few more rules sit around those four:
- The value is a Structured Field string, so on the wire it looks like
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324", quotes included. A UUID is the recommended value. - The server decides how long it remembers keys and should publish that policy. The draft gives no number. 24 hours is a common choice.
- To tell "same request" from "different request", the server may keep a fingerprint of the body, such as a checksum of the whole payload or of selected fields.
- Errors use RFC 9457 problem details.
Revision 08 itself mostly updates references to their current RFCs (9110, 9457, 9562 and 9651) and adds a third author. The one change to the rules is new text for the retry case, which the changelog says is "still open for discussion". So expect that row of the table to move before this becomes an RFC.
The four cases by hand
Here they are against our sandbox on 14 November, with the noisy headers removed:
$ curl -i -X POST https://api.testingapis.com/api/Payments \
-H 'Content-Type: application/json' \
-d '{"userId":101,"amount":49.99,"currency":"usd","method":"card","cardLast4":"4242","description":"Order #1001"}'
HTTP/1.1 400 Bad Request
{"status":400,"error":"Bad Request","message":"Missing Idempotency-Key header. Send a unique value (e.g. a UUID) per logical payment."}
# The same request with a key: the payment is created.
$ curl -i -X POST .../api/Payments -H 'Idempotency-Key: e1c86f2a-ab55-4a5a-ab9b-ff0530fc0cc2' -d '{...}'
HTTP/1.1 201 Created
{"message":"Payment created successfully","idempotencyKey":"e1c86f2a-...","data":{"id":14,"amount":49.99,"status":"succeeded",...}}
# A retry with the same key. The fields are in a different order.
$ curl -i -X POST .../api/Payments -H 'Idempotency-Key: e1c86f2a-ab55-4a5a-ab9b-ff0530fc0cc2' \
-d '{ "description":"Order #1001","userId":101,"amount":49.99,"currency":"usd","method":"card","cardLast4":"4242"}'
HTTP/1.1 201 Created
idempotent-replayed: true
{"message":"Payment created successfully","idempotencyKey":"e1c86f2a-...","data":{"id":14,...}}
# The same key with a different amount.
$ curl -i -X POST .../api/Payments -H 'Idempotency-Key: e1c86f2a-ab55-4a5a-ab9b-ff0530fc0cc2' -d '{..."amount":99.99...}'
HTTP/1.1 422 Unprocessable Entity
{"status":422,"error":"Unprocessable Entity","message":"This Idempotency-Key was already used with a different request body."}The retry is the important one. Its body has the fields in a different order, and the server still treats it as the same request. It returns payment 14 again and marks the response with idempotent-replayed: true. Comparing raw bytes instead of parsed JSON is a common way to get this wrong. A client that rebuilds the body on retry would then get a 422 for a request that is identical in every way that counts.
The same checks as a test file
These tests use only Node's built-in test runner, so there's nothing to install. Set URL and change body to fit your own endpoint:
// Checks a POST endpoint against draft-ietf-httpapi-idempotency-key-header-08.
// URL=https://api.testingapis.com/api/Payments node --test idempotency.test.mjs
import { test } from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
const url = process.env.URL ?? "https://api.testingapis.com/api/Payments";
const body = { userId: 101, amount: 49.99, currency: "usd", method: "card", cardLast4: "4242" };
const post = (key, payload = body) =>
fetch(url, {
method: "POST",
headers: { "content-type": "application/json", ...(key && { "idempotency-key": key }) },
body: JSON.stringify(payload),
});
const json = async (res) => ({ status: res.status, type: res.headers.get("content-type"), body: await res.json() });
test("missing key: 400", async () => {
const r = await json(await post(null));
assert.equal(r.status, 400);
});
test("retry with the same key and body: same result, nothing created twice", async () => {
const key = randomUUID();
const first = await json(await post(key));
const again = await json(await post(key, { ...body })); // a new object, same content
assert.equal(first.status, 201);
assert.equal(again.status, first.status);
assert.equal(again.body.data.id, first.body.data.id);
});
test("same key, different body: 422", async () => {
const key = randomUUID();
await post(key);
const r = await json(await post(key, { ...body, amount: 99.99 }));
assert.equal(r.status, 422);
});
test("five parallel requests with one key create one payment", async () => {
const key = randomUUID();
const results = await Promise.all(Array.from({ length: 5 }, () => post(key).then(json)));
for (const r of results) assert.ok([201, 409].includes(r.status), `got ${r.status}`);
const ids = new Set(results.filter((r) => r.status === 201).map((r) => r.body.data.id));
assert.equal(ids.size, 1, `created ${ids.size} payments`);
});
test("a quoted key and a bare key are the same key", async () => {
const key = randomUUID();
const send = (value) =>
fetch(url, {
method: "POST",
headers: { "content-type": "application/json", "idempotency-key": value },
body: JSON.stringify(body),
}).then(json);
const bare = await send(key);
const quoted = await send(`"${key}"`);
assert.equal(quoted.body.data.id, bare.body.data.id, "the quoted retry created a second payment");
});
test("errors are problem+json (RFC 9457), as the draft's examples are", async () => {
const r = await json(await post(null));
assert.match(r.type ?? "", /application\/problem\+json/);
assert.equal(typeof r.body.title, "string");
});The run against our sandbox:
$ node --test idempotency.test.mjs
✔ missing key: 400 (204ms)
✔ retry with the same key and body: same result, nothing created twice (181ms)
✔ same key, different body: 422 (59ms)
✔ five parallel requests with one key create one payment (131ms)
✖ a quoted key and a bare key are the same key (73ms)
AssertionError [ERR_ASSERTION]: the quoted retry created a second payment
actual: 29,
expected: 28,
✖ errors are problem+json (RFC 9457), as the draft's examples are (34ms)
AssertionError [ERR_ASSERTION]: The input did not match the regular expression /application\/problem\+json/.
actual: 'application/json; charset=utf-8',
ℹ tests 6
ℹ pass 4
ℹ fail 2The concurrency test passed, but it hasn't proved much. All five parallel requests came back 201 with the same payment ID. Our endpoint finishes quickly, so the later requests found a stored response rather than one in progress, and the 409 path never ran. If your endpoint calls a slow downstream service, this test is the one most likely to find a real bug. That's the window where two workers can each decide they're first.
The failure that creates a duplicate
The problem+json failure is cosmetic. The status codes are right and the message explains the problem, only the format is plain JSON. The quoting failure is the serious one. The server stored 30b45acc-… and "30b45acc-…" as two different keys, so the same payment went through twice:
$ curl -s -X POST .../api/Payments -H 'Idempotency-Key: 30b45acc-34f9-48dd-86c7-a88cf0167f82' -d '{...}'
HTTP/1.1 201 "idempotencyKey":"30b45acc-34f9-48dd-86c7-a88cf0167f82" "id":23
$ curl -s -X POST .../api/Payments -H 'Idempotency-Key: "30b45acc-34f9-48dd-86c7-a88cf0167f82"' -d '{...}'
HTTP/1.1 201 "idempotencyKey":"\"30b45acc-34f9-48dd-86c7-a88cf0167f82\"" "id":24Nobody types quotes by hand, so how does this happen? Most APIs today document the bare form, and most clients send it. A client written from the draft sends the quoted form. If one service retries through a library that follows the draft, and the first attempt came from code that didn't, the server sees two keys. The cause is a gap between two habits, not a mistake in either.
The fix belongs on the server, because you don't control every client. Accept both forms and reduce them to one stored key:
// Accepts both the draft's quoted form and the bare form, so they map to the same stored key.
export function readIdempotencyKey(raw) {
if (raw == null) return null;
const value = raw.trim();
const quoted = /^"((?:[^"\\]|\\.)*)"$/.exec(value);
const key = quoted ? quoted[1].replace(/\\(["\\])/g, "$1") : value;
return key.length > 0 && key.length <= 255 ? key : null;
}Call it wherever the header is read, before the key is looked up or stored. Do it before your keys outlive a deploy, because keys stored in the old form won't match the new one. Then add the quoted-key test to your suite so the fix stays fixed.
Before you call your endpoint idempotent
- A missing key on a required operation returns 400 and says what to send.
- A retry with the same key returns the first result, even when the body's key order or whitespace differs.
- A changed body with a reused key returns 422 and creates nothing.
- Parallel requests with one key create one record. Test with a slow dependency, not just a fast one.
- Quoted and bare keys are the same key.
- The key lifetime is written in your docs, and the response to an expired key is too.
Our lesson on idempotency keys covers the client side: generating keys, keeping one key across retries, and what to do when a request times out after it may have succeeded.