Design an Idempotent, Exactly-Once Request Path

Foundations & Core PatternsMediumdesign-idempotent-request-path

Design an Idempotent, Exactly-Once Request Path

Design the mechanism that lets a client safely retry any mutating request — after a timeout, a crash, or a duplicate webhook — without the effect happening twice.

Idempotency KeysDeduplicationEffectively-Once DeliveryOutbox

Traffic & Capacity Estimates:

50k mutating requests/second · 24h dedup window · zero tolerance for double effects

Functional Requirements

•Accept a client-supplied idempotency key on every mutating request and replay the original response for duplicates.
•Distinguish an in-flight duplicate (return 409 or wait) from a completed one (replay the stored result).
•Persist the response atomically with the side effect so a crash between the two is impossible.
•Expire keys after a documented window and reject reuse with a different request body.

Non-Functional Requirements

•Dedup lookup adds under 5ms to the request path.
•Correctness must hold across process crashes, network partitions, and concurrent duplicate submission.
•Storage for keys must be bounded — the dedup table cannot grow forever.

Back-of-the-Envelope Math

50k RPS * 86,400s = 4.3B keys/day; at a 24h TTL and ~200 bytes each, ~860 GB of dedup state.
A Redis dedup layer fronting a durable table cuts the hot-path reads by ~99%.

Key Architectural Trade-offs

Unique-constraint insert in the same transaction as the effect (simple, correct, ties you to one database) vs a separate dedup store (scales, opens a two-store atomicity gap).
At-least-once delivery plus idempotent consumers vs chasing true exactly-once — the former is what production systems actually build.
Transactional outbox for downstream effects vs dual-writes to the database and broker, which silently diverge under partial failure.

Click or drag a component onto the canvas, then connect the handles to draw the data flow.

3 nodes · 2 edges

Components · 35

Client & Edge4

Compute & Gateway7

Storage & Caching11

Messaging & Streaming6

Coordination & Ops5

Intelligence2

React Flow