← All notes
API Development4 min

A request ID is not an idempotency key

When a partner times out on create-print-job or a checkout POST, the support thread often starts with "send us the request id." That header is the right tool for finding one HTTP attempt across gateway, API, and worker logs. It is the wrong tool for deciding whether a second attempt should mutate anything. We keep seeing teams reuse X-Request-ID — or mint a fresh UUID per attempt and call it an idempotency key — and then wonder why double submits still land twice. Observability labels a hop. Idempotency keys claim a business intent.

Two headers, two jobs

A request ID (X-Request-ID, X-Correlation-ID, or a traceparent) answers: which attempt is this, and how do I stitch its logs? Gateways generate one per inbound call if the client did not send one. Proxies may overwrite it. Workers that fan out work mint child spans. The ID is allowed to be unique per network try — that is the point of debugging retries.

An idempotency key answers: which user action is this, across every attempt that action produces? The client mints it once when the operator clicks Submit, stores it with the in-flight form, and resends the same key on timeout. The server reserves that key before side effects and returns the stored outcome on a replay. Same key, same result. New key, new side effect.

Where the mix-up burns you

Al's Flowers and similar print pipelines retry when PrintNode or Shopify webhooks are slow. If the API treats the gateway-assigned request ID as the dedupe key, every retry looks new — because it is a new hop — and you mint a second ticket. If the mobile client regenerates "idempotency" on each axios retry interceptor, you get the same failure mode with a more confident name on the header.

The inverse mistake is quieter: logging only the idempotency key and skipping a per-attempt request ID. Support can prove the business op was unique but cannot tell which of three timed-out POSTs actually reached the worker. You want both: a stable idempotency key for the write, and a fresh request ID for each wire attempt.

What the server should enforce

On state-changing routes, require Idempotency-Key (or an equivalent field) scoped to the caller — typically (tenant, key). Insert or reserve first; do not check-then-act. Store a fingerprint of the body with the reservation so a reused key with a different payload fails closed instead of silently returning the wrong charge.

Never invent the idempotency key on the server from the request ID. Never accept "missing key means generate one for them" on POST create paths that money or fulfillment care about — that makes every lost response a possible duplicate. Echo both IDs in the response and in structured logs so a support engineer can ask for the right one.

How we talk about it in reviews

In API reviews we ask two questions in order. First: what is the client-owned key for this intent, and where is it minted? Second: what is the per-attempt request ID path through the gateway? If the answer to either is "we use the same UUID," the design is unfinished.

Document the retention window for idempotency records separately from log retention. Logs can drop in days; the key store has to outlive the longest legitimate client retry, including operator double-clicks and flaky cellular. That window is a product decision, not a logging TTL.

Have something to build?

Tell us what you're working on and we'll tell you honestly whether we're the right fit.

Work with us