Your agent retries. Did the action already happen?

Your agent requests a report. The report is saved, but the reply never reaches the agent. It tries again and creates a second report. The visible failure was in the acknowledgement. Repeating the write turned that uncertainty into a duplicate. A timeout alone cannot tell you which part completed.¹

Give one intended action a stable identity

An idempotency key identifies an intended operation across attempts. The server can use it to recognise a retry and return a recorded result. Generate the key once for that operation and preserve it when retrying. Generating a new key for every attempt defeats this purpose. AWS describes this distinction between a retry and a new intention in its API design guidance.¹

The key also needs a scope. Two users must not accidentally share the same operation identity. A tenant or user boundary, a retention policy and an explicit definition of what counts as the same request belong in the design. Avoid putting personal or sensitive information in the key. Stripe’s API documentation gives a concrete provider example, rather than a rule that every service implements identically.²

Keep the result and receipt together

For this lesson, Forenta ran a small synthetic SQLite experiment. It writes a report and records its request identity in the same local database. The first call commits, then the example deliberately discards its response. Repeating the unprotected request produces two report rows. In the protected case, the repeated request resolves to the existing row and the total remains one. This is a test of our own fixture, not a recording of Claude Code or Codex executing a workflow.

The protected fixture stores a hash of the request content beside the identity. Reusing the key with different content produces a conflict rather than silently returning an unrelated result. The result and its identity are committed in one transaction, with a unique database constraint on the key. SQLite’s transaction documentation explains the local commit boundary and its single-writer behavior.³

Test the failure path before trusting the happy path

Do not stop at a successful first request. Repeat the exact request after pretending its reply was lost. Compare the saved output, identity and result returned by both attempts. The expected behavior in this fixture is one report and the same receipt. Then change the content while keeping the identity. The expected behavior is an explicit conflict and no additional report.

Next, send the same operation concurrently using independent workers. A read followed by a write can race unless the storage boundary enforces the decision atomically. Our recorded single-process experiment does not establish a concurrent or distributed guarantee. Treat that result as unknown until your implementation has its own test. Include an interrupted request and recovery after restart when those are part of the workflow.¹ ³

A local receipt ends at the local boundary

A database row does not by itself protect an email, payment or publication sent to another system. The external service might complete its action before the local process records success. Recording a receipt first can fail in the opposite direction: the receipt exists but the external action never happened. These are separate failure cases. AWS’s outbox guidance discusses the dual-write problem and notes that duplicate message delivery still requires idempotent consumers.⁵

Use the receiving service’s actual idempotency and reconciliation contract where available. Check how long it retains keys, what it returns after failure, how it compares request content and what happens during concurrent execution. Provider behavior can differ even across API versions. Never transfer one provider’s retention window or error behavior to another without checking its documentation.²

HTTP also distinguishes idempotent method semantics from arbitrary application actions. A client should not automatically retry a non-idempotent operation unless it has a basis for knowing that repetition is safe or the original request was not applied. Calling something a retry is not that basis.⁴

Turn the check into a plan you can review

Use the prompt above with Claude Code or Codex to inspect one bounded workflow. Ask for file locations, the current failure behavior and a proposed test before authorising changes. Keep production writes and messages out of that first pass. The coding agent’s answer is a proposal: inspect the evidence and run the harmless tests yourself.

If you want a second view on the plan, Forge assesses the text you provide. Paste your intended action, retry boundary, assumptions and acceptance checks. Forge does not automatically import or audit your repository. A text assessment cannot certify that your external service handles a retry safely.