Error classification and propagation
Not all failures are the same kind, and the kind decides who handles them.
5 min read · Lesson 10 of 12 in this domain
Agentic systems fail in three distinguishable ways, and conflating them is what produces both useless retry loops and silent wrong answers. A tool error is the tool itself failing — a 500, a timeout, a malformed response from an upstream API. A reasoning error is the model making a bad decision with working tools — wrong tool, wrong argument, wrong conclusion. An environment error is the world not matching expectations — a file that vanished, a permission revoked, a record that no longer exists. Each has a different owner: tool errors belong to your retry code, reasoning errors belong back to the model with enough detail to self-correct, and environment errors usually need a human or a changed plan, because retrying will not conjure the missing file.
- Tool errors are infrastructure. Retry them inside the tool with backoff; do not spend model turns on them.
- Reasoning errors need the model. Return a
tool_resultwithis_error: trueand specific validation detail so it can correct its input. - Environment errors are state mismatches. Retrying is usually futile — surface them so the plan can change or a human can intervene.
- Propagation matters as much as classification: a subagent that swallows any of these and returns an empty result makes the coordinator draw a false conclusion.
- Structured error context — what failed, at which step, how far it got — is what lets a coordinator choose between retry, reroute, degrade and escalate.
| Kind | Example | Who handles it |
|---|---|---|
| Tool | API timeout, 503, malformed upstream JSON | Your retry logic, inside the tool |
| Reasoning | Wrong tool chosen, invalid argument, bad inference | The model, via an informative is_error result |
| Environment | File deleted, permission revoked, record missing | Replan or escalate — retrying will not help |
Distractors offer a single uniform retry policy for every failure. Retrying a permanent environment error three times is pure waste; not retrying a transient one wastes model turns.
A tool returns 503 on a transient network blip. Whose problem is it?
Predictable infrastructure noise should never consume model turns.
An agent passes an invalid enum value and the tool rejects it. What should the result contain?
This is a reasoning error; specific feedback is exactly what lets the model self-correct.
Practise this domain with 27%%-weighted questions in the study app.
Open in study appSource: Claude Docs — Tool use overview · Independent study aid, not affiliated with or endorsed by Anthropic.