Express Idempotency Middleware and Client Retry Semantics

Answer

Direct answers to the three questions:

• When the idempotency key has expired, the server cannot distinguish a retry from a new request; therefore it should treat an unknown key as a new operation only if the key’s TTL exceeds the client’s maximum retry window. If that window is unknown, you must obtain it before deciding.
• If the idempotency datastore is unreachable during a retry, the middleware should fail‑closed: return 503 Service Unavailable (with a Retry‑After header) and not execute the write, preserving the no‑duplicate guarantee.
• The choice between token‑based and store‑based idempotency middleware does not change the fundamental safety contract; both require durable server‑side state to detect replays. Pure stateless tokens only give a limited‑window duplicate check and are weaker against delayed retries.

Confirmed facts (from the research)

• Express provides no built‑in idempotency or retry handling; idempotency is implemented as middleware that reads the Idempotency-Key header, checks a durable store (commonly Redis), and replays the stored response on a matching key.
• A legitimate retry resends the same key with an identical request payload; matching key + identical fingerprint → replay; matching key + different payload → error (commonly 422/409).
• Key expiration removes the ability to distinguish retries from new requests, so the TTL must be set longer than the client’s maximum retry interval.
• When the backing store is unavailable, failing closed (503) is the safe default for write‑like endpoints; failing open risks duplicate writes.
• Token‑based and store‑based approaches both rely on server‑side state; stateless tokens only give a limited‑window duplicate detection.

Likely explanation

The server’s behavior hinges on two observable facts: (1) the presence and validity of the idempotency key in the store, and (2) the ability to reach that store. If the key is missing or expired, the server has no basis to decide whether the request is a retry; the only safe policy is to make that decision depend on a known upper bound for client retries. If the store cannot be contacted, any attempt to proceed risks executing the operation twice, so a fail‑closed response is the only contract‑preserving choice. The middleware implementation (token‑based vs store‑based) does not alter these invariants because both ultimately need persistent server‑side state to detect replays.

Steps needed for this case

1. Determine the client’s maximum retry interval (the longest delay between the original request and a possible retry). If this value is unknown, ask for it before proceeding.
2. Configure the idempotency‑key TTL in the store to be greater than that interval (a common practice is 24 h or more).
3. In the middleware, on store unavailability return 503 Service Unavailable with a Retry‑After header and do not invoke the handler.

Missing diagnostic detail

The only piece of information that can change the recommendation is the client’s maximum retry interval (or the longest delay between the original request and a possible retry). Without knowing this interval you cannot safely choose a TTL that guarantees an expired key will never be mistaken for a new request. Please provide the client’s configured retry back‑off or timeout value.