Law 40 · Architecture & Operations
Retries Demand Idempotency
If an action can run twice, a retry will eventually run it twice.
The principle
Agents retry on timeouts, rate limits, and transient errors, but a failed call that never returned may have already succeeded on the server. Without an idempotency key, the retry that 'fixes' a network blip quietly double-charges the card, double-sends the email, or double-books the room. Safe retries depend on the server being able to dedupe.
Why it happens
The dangerous retry is the one after an ambiguous failure. The server may have charged the card, sent the email, or created the record, while the client only saw a timeout. Retrying without dedupe repeats the side effect. Idempotency keys solve this by naming the logical action: the server stores the first result and replays it for later attempts with the same key. Backoff and jitter matter too, because synchronized retries can overload the dependency you are trying to recover. Any retryable side effect needs both controls.
Watch for
- A side-effecting tool call is retried on timeout with no key that lets the server recognize a duplicate.
- Retries fire immediately or on a fixed interval rather than with exponential backoff and jitter.
- You have seen duplicate charges, emails, or records traced to a network blip rather than a logic bug.
In practice
Your billing agent calls the charge endpoint, the response times out, and the agent's retry logic dutifully fires again. The first call had already succeeded server-side, so the customer gets charged twice and opens an angry ticket. Network blips are routine, so a retry policy without deduplication will eventually double-charge someone. Generate an idempotency key per logical action and pass it on every side-effecting call so the server collapses the duplicate, and never let an agent blindly re-run a non-idempotent operation.
Apply it
- Generate a unique idempotency key per logical action and send it on every side-effecting call so the server can dedupe.
- Never let the agent blindly retry a non-idempotent operation without that key.
- Retry with exponential backoff and jitter so synchronized retries do not amplify load on a struggling dependency.
The takeaway
Attach a client-generated idempotency key to every side-effecting tool call so the server can dedupe retries. Never let an agent blindly retry a non-idempotent action.