Short answer
Retry preserves intent; a new decision replaces it
Use the same idempotency key only when the original logical mutation is still the one whose outcome you need to learn. Use a new key after new state leads to new reasoning.
A connection timeout may leave the client uncertain whether the server accepted the request. Resending the same payload and key asks for the outcome of that same intent. No new model choice is required unless the server establishes that the request did not commit and current state has changed.
A version conflict is different. It proves the decision context was stale. The agent must read current state and decide again; labeling that action a retry hides the new observation and new intent.
Decision boundary
Classify the failure before sending another mutation
| Observed result | Next operation | Request identity |
|---|---|---|
| No response; commit unknown | Replay exact request | Same key |
| Stored successful response | Continue from returned state | No new mutation |
| Schema rejection | Repair payload if intent is unchanged | New valid request identity |
| Version conflict | Reread and reason again | New key for new decision |
| Rate limit before commit | Wait, then follow server contract | Preserve logical intent where specified |
Failure modes
Two shortcuts create opposite reliability bugs
Always creating a new key risks duplicate effects; always reusing the old key risks replaying obsolete intent or triggering a payload mismatch.
The first bug appears when a client treats a missing response as a new request. The server may already have committed the first call, so the second identity can authorize another transition if it remains legal.
The second appears when an agent rereads state, chooses a changed action, and sends it under the old key. A correct server rejects that mismatch because one identity cannot safely name two logical mutations.
Evaluation
Make the retry boundary visible in the run record
Record request identity, payload fingerprint, response status, state version, and any intervening read so reviewers can tell retransmission from re-decision.
- Count network sends separately from logical requests and authoritative effects.
- Verify an exact retry returns one stored outcome.
- Verify a conflict leads to a fresh observation before a new action.
- Treat repeated unbounded sends as behavior, even when none commits twice.