Retries, idempotency and duplicate actions

Learning outcome: Handle an uncertain write without blindly repeating it.

A timeout does not always mean an operation failed. A server may have performed the write while the response was lost. Retrying without checking can create duplicate tickets, messages or orders.

Idempotency means repeating an operation has the same intended effect as performing it once. Some services support an idempotency key that identifies one logical operation. Where that is unavailable, use an authoritative status lookup or another suitable deduplication design. Record the operation identity and distinguish confirmed failure from unknown outcome. Never let an agent equate silence with permission to repeat a consequential action.

Worked example

A fictional draft-creation call times out after the server stores draft D-104. The assistant repeats the request and creates D-105. A safer design keeps a stable operation key, checks whether the first draft exists and returns that identifier when appropriate. The user should not have to discover duplicated work later.

Try it yourself

Draw the success, confirmed rejection and timeout branches for creating a draft. State which branch may safely retry and what evidence is needed first.

You can do this exercise on paper. If using an assistant, keep to the fictional material and an approved tool.

Check your understanding

After a write request times out, what should be assumed?

1. The outcome may be unknown until checked
2. The write definitely failed
3. The write definitely succeeded

Workbook

Download the course workbook to record your answer and compare it after the knowledge check.

Further reading

• Anthropic: building effective agents
• Anthropic: writing tools
• MCP architecture