Intermediate · INTERACTIVE LESSON

Idempotency keys

Follow write retries through reservation, result replay, conflicts and key expiry.

The interactive player is loading. If it does not appear, you can still read the explanation below.

THE IDEA BEHIND THE STEPS

How it works

Imagine retrying a payment because you do not know whether it finished. Reusing an idempotency key with the same payload lets the service share one logical result within a retention window. This model compares identical scheduled write attempts against independent services with and without deduplication. Each completed unprotected attempt performs one effect; a protected attempt first checks a shared key registry.

An absent key is atomically reserved with its payload. Matching attempts while it is in-progress wait for that operation; matching attempts after completion replay its stored result. A different payload with the same retained key is rejected in either state. Completion atomically performs one effect and stores its result, then responds to every waiter. Result IDs identify simulated effects, not real payment records. A replay returns the original result, not a new write.

Only completed entries expire, at completion time plus TTL. At t >= expiry the entry becomes absent. A retry after expiry can perform another effect, even with the same key and payload. Waiting and replay do not extend retention. In-progress reservations do not expire in this model; all work finishes after a fixed bounded duration. Real systems must handle abandoned reservations and uncertain outcomes carefully.

Enter up to 12 attempts as time:client:key:payload, separated by commas. Time is an absolute integer second (0–30); clients are 1–3; keys and payloads are case-sensitive 1–8 character letters, digits, underscores or hyphens. Input order breaks ties; attempts otherwise run in time order. These are explicitly scheduled attempts, including retries, not an automatic retry algorithm. The same key can be shared by different clients; different keys never deduplicate, even when their payloads match.

At each timestamp, process completions, then completed-entry expiration, then arrivals. Completion ties and arrival ties use original attempt ID. All clients use one shared registry. Network animation adds no simulated time. Effects count committed writes, waits count attempts joining in-progress work, replays count stored-result responses, and conflicts count rejected payload mismatches. The unprotected comparison ignores keys and performs every submitted write, including conflicting payloads.

Atomic reservation and atomic effect/result storage are explicit assumptions. This is not a protocol for exactly-once delivery: requests may repeat, retention ends, and real crashes can split effects from result storage unless the storage design prevents it. External effects such as charging a separate provider cannot be assumed atomic with a local database. Longer retention costs storage; shorter retention increases the risk from late retries. This bounded teaching model excludes crashes, failures, lost replies, authentication/tenant scoping, automatic retry/backoff, network latency and distributed coordination races. It makes no production throughput or availability guarantee.