Idempotency-Key: retrying POST /orders without creating a second order Intermediate

The problem

A shopper taps Pay in a mobile app. The app sends POST /orders for one pair of shoes, qty: 1. The API creates order 1 and charges the card, but the 201 response is lost on a flaky 4G link.

After its 10-second timeout (illustrative), the app does not know whether the order exists.

If the app sends the same POST again, the API sees a brand-new request and creates order 2. If the app gives up, the shopper may tap again and get the same result. Neither choice is safe.

The question: how does an API let the client retry a POST and still produce exactly one order? Webhooks and consumers have their own dedupe articles; this one covers the HTTP API layer.

Which design? (summary first)

Situation	Choose	Condition
Client creates an order or payment and may retry after a timeout	Idempotency-Key + stored response	Key scoped per user + endpoint, fingerprint, TTL above the retry window
The client can choose the resource URI	PUT /orders/{clientId}	PUT is already idempotent
The work is slow (calls a payment gateway)	Two-phase claim, 409 for a concurrent duplicate	A lease to recover keys stuck in_progress
The work is short and only touches PostgreSQL	Claim + effect in one transaction	The duplicate waits on the unique index instead of getting 409

Core concepts

Why POST is not idempotent

RFC 9110 §9.2.2 calls a method idempotent when several identical requests have the same intended effect as one. PUT, DELETE and safe methods (GET, HEAD, OPTIONS, TRACE) are idempotent; POST is not, and neither is PATCH (RFC 5789).

Hence a client SHOULD NOT automatically retry a non-idempotent request unless it can know the request is idempotent or was never applied. Idempotency-Key provides that knowledge: a contract the server publishes per endpoint.

The Idempotency-Key header

The header is an IETF httpapi working group Internet-Draft, not an RFC: draft-ietf-httpapi-idempotency-key-header-08 (22 October 2026). Stripe’s API already uses the same header name. The draft says:

Topic	Draft-08 text (paraphrased)
Syntax	Structured Field Item, value must be a String: Idempotency-Key: "6f1c2a8e-..."
Key value	Unique, must not be reused with a different payload; UUID or similar random value recommended
Fingerprint	Optional: the server may combine the key with a hash of the payload
Expiry	The resource should define an expiry policy and publish it in its documentation
Missing key	400 when the documented operation requires the header
Same key, different payload	422
Duplicate while the first is still processing	409

Stripe sends the value unquoted and allows up to 255 characters. The draft may still change; follow the server’s documentation.

How it works

A lost 201 followed by a retry with the same key still produces one order

Enlarge diagram

Mobile app → Orders APIPOST + K1

◀ Prev▶ PlayNext ▶↺ RestartStep 1/6

The user taps Pay once. The app creates key K1 for this intent and sends POST /orders.

State after each step:

1. Request: the app holds key K1 for this tap; the database is empty.
2. Claim: row (7, POST /orders, K1, in_progress); the primary key blocks a second row.
3. Effect: order 1, outbox event and response_code = 201 commit together.
4. Response lost: server state is final; only the client is uncertain.
5. Retry: the claim returns 0 rows; the API reads the existing row.
6. Replay: fingerprint matches, status completed: the stored 201 goes back. Still one order.

Atomic claim on PostgreSQL 17

The scope is (user_id, endpoint, key), so two users with the same UUID never collide. The fingerprint is a SHA-256 of method, path and canonical JSON body. The claim is one statement; SELECT then INSERT races, as upsert with ON CONFLICT shows.

CREATE TABLE idempotency_keys (
  user_id       bigint      NOT NULL,
  endpoint      text        NOT NULL,
  idem_key      text        NOT NULL,
  request_hash  text        NOT NULL,
  status        text        NOT NULL CHECK (status IN ('in_progress', 'completed')),
  response_code int,
  response_body jsonb,
  locked_until  timestamptz,                    -- lease for in_progress rows
  expires_at    timestamptz NOT NULL DEFAULT now() + interval '24 hours',
  PRIMARY KEY (user_id, endpoint, idem_key)
);

INSERT INTO idempotency_keys (user_id, endpoint, idem_key, request_hash, status, locked_until)
VALUES ($1, $2, $3, $4, 'in_progress', now() + interval '30 seconds')
ON CONFLICT (user_id, endpoint, idem_key) DO NOTHING
RETURNING idem_key;

One returned row means this request owns the key. Zero rows means another request got there first; the handler reads the row and decides:

Existing row	Response	Why
Different request_hash	422	Key reused for another intent (draft-08)
Same hash, in_progress	409 (or wait)	The first attempt has not finished
Same hash, completed	Stored status + body	The retry gets what the first attempt got

Concurrent duplicate: 409 or wait

A retry can arrive while the first request is still calling the payment gateway. What happens depends on when the claim commits.

Two-phase claim: the retry gets 409 while A is in progress, then the stored 201

◀ Prev▶ PlayNext ▶↺ RestartStep 1/5

A claims K2 in a short transaction and commits status in_progress, then calls the gateway.

• Two-phase (diagram): the claim commits alone, so B sees in_progress at once and gets 409. No lock is held during the gateway call.
• One transaction: the claim is uncommitted until the effect commits. B’s INSERT ... ON CONFLICT waits on the unique index (wait_event = transactionid in the demo), then returns 0 rows. If A rolls back, B’s insert succeeds.

Waiting suits short database-only work. For slow external calls it holds a transaction open for the whole call; prefer two-phase and 409.

Key lifecycle

Loading diagram…

Operational details

• What to store: status code, body and headers the client needs (Location). jsonb reorders keys (see demo line 2); use text if byte-identical replay matters.
• Which outcomes: store results once execution starts. Validation 400s happen before the claim, so the client can fix and resend. Stripe v1 follows this rule and also replays stored 500s.
• TTL: above the longest client retry window, offline queues included. Stripe v1 may prune keys after 24 hours; a pruned key starts a new request. Purge by expires_at with an index.
• Stuck in_progress: a crash after the claim leaves the row until locked_until; a retry may then take it over with UPDATE ... WHERE locked_until < now().
• External side effects: a takeover can call the gateway again, so pass it a derived key. Events go through the transactional outbox in the response’s transaction.
• Errors: 400, 409, 422 as Problem Details with a stable type, like draft-08’s examples.

Real-world example

Checkout on a flaky mobile network

The app generates a UUID v4 when the shopper taps Pay and saves it with the cart. Every retry of that tap, even after an app restart, sends the same key and body. Editing the cart and tapping again gets a new key.

Keys live 24 hours, above the app’s 6-hour offline retry queue (illustrative). A 422 spike points to a client that reuses keys.

The demo runs the handler against PostgreSQL 17 with two connections:

docker compose -f examples/docker-compose.yml up -d postgres
npx --prefix examples ts-node examples/src/idempotency-key/demo.ts

Output (PostgreSQL 17.11)

1. first POST                      -> 201 {"orderId":1,"sku":"SHOE-42","qty":1,"status":"created"}
2. retry, same key + same body     -> 201 (replayed) {"qty":1,"sku":"SHOE-42","status":"created","orderId":1}
3. same key, qty changed to 2      -> 422 {"type":"https://api.example.org/problems/idempotency-key-reused",...}
4. same key, another user          -> 201 {"orderId":2,...}
6b. retry while A in progress      -> 409 {"type":"https://api.example.org/problems/request-in-progress",...}
6a. A finishes                     -> 201 {"orderId":3,...}
6c. retry after A finished         -> 201 (replayed) {...,"orderId":3}
7. purged expired keys: 1
7b. late retry after expiry        -> 201 {"orderId":4,...}
orders now: 4
8. B while A uncommitted: { wait_event_type: 'Lock', wait_event: 'transactionid' }
8. B after A COMMIT: rowCount = 0 (waited ~300 ms)

Lines 2 and 6c replay; line 4 shows the per-user scope. Line 7b is the TTL trap: a retry after the purge creates a second order. Output is abridged with .... The demo lacks lease takeover, a real gateway call and request timeouts.

Trade-offs

What Idempotency-Key gives you

• Clients can retry POST after timeouts without duplicate orders or charges.
• The retry gets the original result, including the created ID.
• 422 exposes client bugs that reuse keys.

Costs and boundaries

• An extra write per request; the guarantee ends at the TTL.
• Two-phase needs a lease and takeover logic for crashed requests.
• External calls still need their own idempotency (gateway key, outbox).

🎮 Try it

• HTTP status code: pick between 400, 409, 412, 422 and 429 for eight API cases, including key reuse and a duplicate in progress.

Production checklist

1. Document which endpoints require Idempotency-Key, the key format, the TTL and the error types.
2. Scope the unique key by caller and endpoint: PRIMARY KEY (user_id, endpoint, idem_key).
3. Claim with INSERT ... ON CONFLICT DO NOTHING RETURNING; never SELECT then INSERT.
4. Store a fingerprint of method, path and canonical body; return 422 on mismatch.
5. Commit the business effect, the outbox row and the stored response in one transaction.
6. Choose 409 or wait for concurrent duplicates; with 409, add a lease on in_progress rows.
7. Set the TTL above the client’s longest retry window and purge expired keys in batches.
8. Alert on 409 and 422 rates per client version.

Common mistakes

Most client bugs come from generating the key at the wrong moment.

One key per user intent, reused on retry

✕ Common

// New key on every attempt: the server sees two different requests
await retry(() => api.post('/orders', cart, { headers: { 'Idempotency-Key': crypto.randomUUID() } }));

✓ Prefer

const key = crypto.randomUUID();          // created once, when the user taps Pay
await retry(() => api.post('/orders', cart, { headers: { 'Idempotency-Key': key } }));

Why

A key generated inside the retry loop deduplicates nothing. Keep it with the intent, and persist it if retries survive an app restart.

Caching the response without checking the body

A key lookup that ignores the fingerprint replays order 1 for a request that asked for qty: 2. The client believes it ordered two pairs. Compare the hash and return 422 instead.

Misunderstanding	Consequence	Do instead
“A unique constraint on orders is enough”	Retry gets an error, not the order ID	Store and replay the first response
“Keys can live in Redis only”	Key and order commit separately; a crash between them breaks dedupe	Key and effect in one database transaction
“A 1-hour TTL is plenty”	Offline queues retry later and duplicate	TTL above the longest retry window

Self-check

1. Two requests with the same key arrive 50 ms apart. What does each get in the two-phase design, and in the single-transaction design?
2. Why must the validation 400 not be stored under the key?
3. The process crashes after the gateway charged the card but before COMMIT. What prevents a second charge on takeover?

Summary

Key takeaways

• POST is not idempotent under RFC 9110; Idempotency-Key makes a specific endpoint safe to retry.
• The header is an IETF Internet-Draft (draft-08), not an RFC: 400 missing, 409 in progress, 422 different payload.
• Claim atomically with INSERT ... ON CONFLICT DO NOTHING on (user, endpoint, key) and store the response.
• Effect, outbox event and stored response commit together; external calls need their own key.
• One key per user intent, reused on every retry, kept longer than the retry window.

References

• draft-ietf-httpapi-idempotency-key-header-08 — IETF: syntax, fingerprint, 400/409/422 cases.
• RFC 9110 §9.2.2 Idempotent Methods: which methods are idempotent and when clients may retry.
• PostgreSQL 17 — INSERT: ON CONFLICT DO NOTHING and RETURNING.
• Stripe — Idempotent requests: key length, 24-hour pruning, which results are saved.
• RFC 9457 — Problem Details: the error body format for 409 and 422.