Idempotency and Retry Design

Design safe retries for payments, webhooks, and jobs: idempotency keys, exactly-once boundaries, backoff, and the failure cases to test.

Design the retry and idempotency behavior for this operation.

The operation and what it does: [e.g. "charge a card and create an order", "process an inbound webhook", "run a nightly sync job"]
Where it runs and what calls it: [SERVICE, QUEUE, CRON, CLIENT]
External systems it touches: [APIS, DATABASES, QUEUES, and whether each is idempotent]
What must never happen twice: [DOUBLE CHARGE, DUPLICATE EMAIL, DUPLICATE ROW]
What is acceptable if it happens twice: [BE EXPLICIT]
Current behavior on failure: [WHAT HAPPENS NOW]
Volume and latency requirements: [NUMBERS]
Relevant code:
"""
[PASTE, OR DELETE THIS BLOCK]
"""

Produce:

1. **Where the operation can fail.** Walk the sequence and name every point where a failure can occur, including the hardest one: after the external side effect succeeded but before we recorded it. That gap is where duplicates come from and it is the reason this design exists.

2. **Idempotency design.** What the idempotency key is derived from, where it is stored, how long it is kept, and what happens on a repeat: return the original result, return a conflict, or no-op. State explicitly what the caller must send and what happens when they do not.

3. **Atomicity boundaries.** Which steps must succeed or fail together, and how that is enforced given that a database transaction cannot cover an external API call. Name the pattern used (outbox, saga, two-phase claim, reconciliation) and its cost.

4. **Retry policy.** What is retryable and what is not, distinguished by error class rather than by status code alone. Backoff strategy with jitter and concrete numbers, maximum attempts, and total time budget. Say what happens when retries are exhausted.

5. **Dead letters and reconciliation.** Where failures land, who looks at them, and the periodic check that catches the cases this design still misses. Every at-least-once system needs one, so say what it compares.

6. **Ordering.** Whether out-of-order delivery breaks anything, and what makes it safe if so.

7. **Test cases.** The specific failures to test: timeout after the side effect, duplicate delivery, concurrent duplicate requests, partial batch failure, and a retry storm after a downstream outage. For each, the expected observable behavior.

Rules: state your assumptions about the idempotency guarantees of each external system rather than assuming they are safe. If a requirement I gave is not achievable (exactly-once across systems without coordination, for example), say so and give the closest achievable design.

How to use

The gap named in section 1 is the whole problem: the side effect landed and the acknowledgment did not, so a retry is both necessary and dangerous. Insisting the design names that window makes the rest concrete. The reconciliation job in section 5 is what teams skip and later wish they had, because every at-least-once pipeline eventually produces a case its retry logic cannot fix, and the only way to find those is to compare the two sides on a schedule.

More coding prompts

Write the commit message for this change.

Diff:
"""
[PASTE THE STAGED DIFF]
"""

Why I made this change: [THE REASON, THE TICKET, THE BUG REPORT, or "you infer it"]
Convention: [Conventional Commits / this repo's existing style, pasted below / plain]
Recent commits from this repo, to match style:
"""
[PASTE 5-10 RECENT COMMIT SUBJECT LIN

Commit Message

Write a commit message that explains why the change was made, in Conventional Commits format, split into separate commits when needed.

Codingbeginner

Help me recover from a git mistake without making it worse.

What I was trying to do: [THE GOAL]
What I ran: [THE EXACT COMMANDS, IN ORDER]
What happened instead: [THE OUTPUT OR THE STATE NOW]
Has this been pushed or shared: [YES/NO, and to which branch and whether anyone else has pulled]
Uncommitted work I cannot lose: [WHAT AND WHERE, o

Undo a Git Mistake

Recover from a bad commit, force push, wrong branch, or lost work with a reversible plan and the exact commands, explained before you run them.

Codingintermediate

Handler code, routes, and models:
"""
[PASTE THE ROUTE DEFINITIONS, HANDLERS, REQUEST AND RESPONSE TYPES, VALIDATION SCHEMAS, AND MIDDLEWARE]
"""

Generate an OpenAPI 3.1 specification from the code above.

API name, version, and base URL: [DETAILS]
Auth scheme: [BEARER JWT / API KEY / OAUTH / SESSION COOKIE, and where it is enforced]
Con

OpenAPI Spec From Code

Generate an accurate OpenAPI 3.1 spec from handler code, including error responses and auth, with gaps flagged instead of invented.