beginner · Interactive lab
Idempotency
The same request can arrive more than once. Learn how an idempotency key lets the receiver create the business effect only once, and why a correlation ID cannot do that job.
By the end: Tell apart logical operations, delivery attempts and business effects.
Your challenge
Start here. This lab opens with a common mistake, and it is wrong: the Warehouse API treats any correlation ID it has seen before as a duplicate, and anything else as new. Read each arrival, decide, and test.
See it happen
Deliver twice, create once
- Integration Logic → Warehouse API: attempt
- Warehouse API → Idempotency ledger: claim / check
- Warehouse API → Orders created: creates
One order, one attempt
Integration Logic asks the Warehouse API to create order ORD-701: one logical operation, one delivery attempt. The Warehouse API creates it and answers 200 OK. One business effect.
Learn more
Why this pattern exists
When an answer is lost, the caller retries, and the Warehouse API may receive the same request again. Three counts stop matching: logical operations (orders someone wants), delivery attempts (sends), and business effects (orders actually created). An idempotency key is a name for one logical operation: the caller creates it once and puts it on every retry, and the receiver keeps a ledger of the keys it has seen. A correlation ID has a different job: it traces a conversation across systems. One conversation can contain several different operations, and a retry sent by another process can start a new trace, so a correlation ID cannot tell a repeat from a new request.
Integration Logic sends orders to the Warehouse API, which keeps an Idempotency ledger and creates orders. Each graded case is one arriving request with a fixed ledger and correlation history. No real API is called.
- Tell apart logical operations, delivery attempts and business effects.
- Decide what a receiver does with an arriving request from its idempotency ledger: new, in progress, completed, or a conflicting reuse of the key.
- Explain why a correlation ID is not duplicate protection, and why the key must be claimed before the business effect.
The rule this lesson applies: Idempotency does not make delivery exactly-once: attempts can still arrive more than once. It makes the business effect happen once for the protected operation. The receiver claims a new key before it creates anything: NEW becomes PROCESSING in one indivisible step (for example, an insert that fails if the key already exists), then the order is created, then the key is marked COMPLETED with its result. Checking the key, creating the order and only then writing the key is not enough: two attempts arriving together can both pass the check. A completed key with the same request is answered by replaying the stored result; a key still in progress starts nothing new; the same key with a different request is a caller mistake and is rejected, not guessed at. Real systems also decide how long to keep keys and what counts as the same request; this lesson keeps those fixed. Scope: this Foundations lesson assumes the idempotency ledger itself is reliable. Claiming the key first prevents the simple check-then-act race, but it is not by itself a complete crash-recovery solution: if the Warehouse API crashes after creating the order but before recording COMPLETED, that is a separate recovery problem. Production systems may address it with transactional coordination, reconciliation, leases with recovery, or related patterns; those mechanisms are outside this lesson.