NOTES / AGENTIC DESIGN PATTERNS

Error handling and recovery

How an agent should treat failures: return them as readable results, classify them, retry what is worth retrying, and stop what is not.

UPDATED 18 NOV 2026#patterns#errors#retries#tool-results

Failures are normal

Tools time out, APIs rate-limit, arguments come out malformed, files do not exist. An agent that treats every failure as fatal is brittle; one that retries everything forever burns money. The design question is what the agent sees when something goes wrong, and what the harness does about it.

Return the error as a result

In Anthropic’s API you still send back a tool_result, with is_error set to true and the message in the content1. The model reads that result and chooses what to do next4. The SDK tool runner does this for you: when a tool throws, it catches the exception and returns it as an error result carrying the exception message rather than the full stack trace2.

Diagram: the model calls a tool, the tool fails, the failure is wrapped as a tool_result with is_error true, and the model reads it and retries, changes arguments, or asks

Diagram: my own, following the is_error mechanism in 1 and 2.

For invalid calls, such as missing parameters, Anthropic’s documentation says Claude will retry two or three times with corrections before apologising to the user, and that strict tool use can eliminate invalid calls1.

MCP draws a similar line. It separates protocol errors, for problems with the request itself such as an unknown tool, from tool execution errors, which are reported in the result with an error flag set4.

Write errors the model can act on

The message is the model’s only information. Anthropic’s example is that a rate-limit error which says when to retry gives Claude what it needs to recover, whereas an opaque failure does not1. Tian Pan makes the same point: error quality decides whether the agent corrects itself or enters a retry loop that burns tokens without converging, and a generic {"error": "invalid input"} is useless3.

Diagram: a vague or noisy error message beside a short message that says what failed and how to fix it

Diagram: my own.

Classify, then respond

The classification below is my own working scheme, not a standard.

Diagram: three classes of failure: transient, fixable input and permanent, with example causes and a response for each

Diagram: my own.

Class Examples Who handles it Response
Transient timeout, rate limit, 5xx harness, below the model retry with backoff and a small cap
Fixable input missing or wrong argument model, via the error result explain the problem, let it retry
Permanent not found, permission denied model and user stop retrying, report, or ask

Handling transient errors in the harness keeps them out of the context window. Fixable-input errors belong in the model’s view because it can fix them. Permanent errors should end the attempt: repeating an identical failing call is the classic no-progress loop.

Recovery strategies

  • Retry with the same call only for transient faults, with exponential backoff and a limit.
  • Retry with changes when the error explains what to change.
  • Try another route: a different tool, a smaller step, or a different query.
  • Degrade gracefully: return a partial result and say what is missing.
  • Escalate to a person (Human in the loop) when the same failure recurs.
  • Resume, do not restart: with checkpoints, a crash costs one step rather than the whole run.

Watch for silent failures

The worst failure is one nobody saw. Verification steps are one defence: the MAST study of multi-agent systems found that missing or incorrect verification is a recurring failure category5. Check the outcome, not only the call: see Trajectories and outcomes and Tracing and monitoring.

Sources

  1. [1]Handle tool calls — Anthropic, Claude Platform docsPARAPHRASED
  2. [2]Tool runner (SDK) — Anthropic, Claude Platform docsPARAPHRASED
  3. [3]Writing Tools for Agents: The ACI Is as Important as the API — Tian Pan · tianpan.co · 2025PARAPHRASED
  4. [4]Designing Tool Errors for Agents — Trida AI, DEV CommunityPARAPHRASED
  5. [5]Why Do Multi-Agent LLM Systems Fail? — Mert Cemri and co-authors · arXiv · 2025FURTHER READING

© Ashish Kumar. All rights reserved. Quoted and cited material belongs to its owners. How I attribute sources.

Product, company and framework names are trademarks of their respective owners. Mentioning them does not imply affiliation or endorsement.