Idempotency Receipt Store Design Prompt
Design an idempotency receipt store that records the result of each first-time request keyed by an idempotency key, so retries return the original outcome instead of re-executing the side effect.
- Target user
- Backend and platform engineers making automation retries safe
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior backend engineer who has cleaned up the mess from a retried request that ran a side effect twice. I will provide: - The operation being made idempotent and its side effects (DB write, payment, provisioning) - Who supplies the idempotency key and how it's generated - The datastore available for the receipt store and its consistency guarantees - Concurrency expectations and how retries are issued (client, queue, automation) Your job: 1. **Key contract** — define what the idempotency key covers, its scope (per-endpoint, per-tenant), and TTL; reject reuse of a key with a *different* request body as a conflict. 2. **Receipt lifecycle** — model the receipt states (in-progress, succeeded, failed) and the atomic claim that lets exactly one request transition from absent to in-progress for [OPERATION]. 3. **Concurrent-retry handling** — specify what a second concurrent request with the same key does while the first is still in-progress (block, return 409, or wait), avoiding two executions racing. 4. **Result capture** — store enough of the original response to replay it byte-for-byte to a retry, including the status and body. 5. **Failure semantics** — decide whether a failed first attempt is retryable under the same key or must surface the stored failure, and justify it. 6. **Cleanup and storage** — define TTL/eviction so the store doesn't grow unbounded, and the consistency level required so the claim is truly atomic. Output as: a receipt schema, the atomic claim pseudocode, a state diagram, and a concurrency test plan covering duplicate, concurrent, and conflicting-body requests. Validate the atomic claim under real concurrency in staging — fire N simultaneous requests with the same key and assert exactly one side effect; an idempotency layer that isn't atomic is worse than none because it gives false confidence.
Why this prompt works
An idempotency key is only as good as the store behind it, and that store is where most implementations quietly break. The naive version checks whether the key exists, sees that it doesn’t, and proceeds — but between the check and the write, a concurrent retry does the same thing, and now the side effect runs twice. The prompt makes the atomic claim the centerpiece: the transition from “key absent” to “key in-progress” must be a single conditional insert or compare-and-set, so exactly one request wins and every other request observes that it lost. This is the difference between an idempotency layer that works and one that gives false confidence under load, which is the only time it matters.
The prompt also forces decisions that teams usually leave implicit and regret later. What does a second request with the same key but a different body mean? Returning the original result silently masks a real client bug, so the prompt requires treating it as a conflict. What happens to a failed first attempt — is the key burned, or retryable? Leaving this undefined either blocks legitimate retries or replays a stale error to a caller who’d succeed on a fresh try. By demanding explicit receipt states and failure semantics, the prompt turns these into design choices you can defend rather than emergent behavior you discover in an incident.
The required concurrency test plan is what keeps this honest. The model can draft a plausible schema and claim logic in seconds, but the only proof that the claim is actually atomic is firing many simultaneous same-key requests in staging and asserting exactly one side effect occurred. You own that verification, because an idempotency bug fails silently: everything looks fine until the one retry storm that double-charges or double-provisions.
Related prompts
-
Idempotency-Key Write Path Design Prompt
Design an idempotency-key scheme for an automation that makes external write calls — key derivation, store, conflict handling, and TTL — so retries, replays, and concurrent runs cannot create duplicate orders, charges, tickets, or resources.
-
Webhook Dedupe and Replay-Protection Receiver Design Prompt
Design a hardened inbound webhook receiver that verifies signatures, rejects replayed or stale deliveries, and deduplicates at-least-once redeliveries so automated downstream actions fire exactly once per real event.