Error Categories

When a tool fails inside an agent, how it reports the failure decides whether Claude can recover. A generic status like "Operation failed" tells the model nothing — it can't tell a temporary blip from a permanent block, so it either retries blindly or gives up.

The fix is a structured error: a small object that names the kind of failure. The core field is errorCategory, which takes one of four values:

• transient — temporary, likely to succeed on retry
• validation — the request was malformed
• business — a domain rule blocked it
• permission — access was denied

This lesson teaches you to recognize each category and route on it.

A well-designed MCP tool error carries more than a message. It flags itself as an error, names a category, and says whether retrying could help.

Notice the fields: isError marks it as a failure, errorCategory classifies it, and isRetryable gives an explicit yes/no on retrying. The extra fields — attempted_query and partial_results — let the coordinator recover intelligently instead of starting over.

Transient errors are temporary and not your request's fault: a timeout, a brief network drop, an upstream service that is momentarily overloaded. The same call, made again a moment later, is likely to succeed.

These map to isRetryable: true. The right move is almost always to retry locally inside the subagent — recover the fault where it happened, with a short backoff, rather than aborting the whole workflow over a hiccup.

Validation errors mean the request itself was malformed: a missing required field, a wrong type, an out-of-range value, a bad date format. The tool never got far enough to do real work.

Blindly retrying the identical request will fail again — so isRetryable is usually false. But the error is still recoverable: Claude can read the message, fix the input, and call again. The richer the message (which field, what was expected), the faster the model corrects itself.

Business errors happen when the request is well-formed and the caller is allowed, but a domain rule forbids the action. Think: refund exceeds the policy ceiling, account balance too low, item out of stock, booking past the cutoff time.

This is not a bug to retry — it's a real-world constraint. isRetryable is false. The agent should surface the rule clearly, and if the workflow can't proceed within policy, escalate rather than try to force the action.

Permission errors mean access was denied: the credential, token, or role does not authorize this action or resource. The request may be perfectly valid in shape and intent — it's simply not allowed.

Retrying the same call with the same credential will keep failing, so isRetryable is false. The agent should not loop; it should report the access gap and, when appropriate, escalate to a human or a privileged path.

The whole point of categorizing is to route. Once the coordinator reads errorCategory, the recovery path is deterministic — it doesn't have to guess by reading prose.

A clean mapping:

• transient → retry locally with backoff
• validation → fix the input, then retry
• business → respect the rule; escalate if blocked
• permission → stop; report / escalate the access gap

This is intelligent routing that a generic "failed" status simply cannot support.

You don't always have to branch on all four categories. The isRetryable flag is a quick gate: true means "trying again could plausibly work," false means "the same call will fail the same way."

As a rule of thumb, only transient errors are retryable as-is. Validation needs the input changed first; business and permission won't change on retry at all. Treat isRetryable: false as a hard signal to stop retrying and choose a different action — repair, escalate, or report.

A subtle but exam-critical distinction: an access failure is not the same as a valid empty result.

If a lookup tool can't reach the database, that's a transient error — maybe retry. If it reaches the database fine and there are simply no matching rows, that is a successful call returning zero results — isError is false. Conflating the two leads to pointless retries on "no matches found," or worse, silently treating a real failure as "nothing there."

When a non-recoverable failure must propagate up, send structured context with it — not just "it broke." Include the failure type, the attempted_query, any partial_results already gathered, and viable alternatives.

In a multi-agent research system, this is what lets the coordinator annotate coverage gaps and still assemble a useful answer from what succeeded. The two failure modes to avoid: silent suppression (swallowing the error) and aborting the entire workflow because one of ten subtasks failed.

Put the two halves together into one operating principle for agent error handling:

• Recover transient faults locally — retry inside the subagent with backoff; don't bubble a timeout all the way to the human.
• Escalate non-recoverable failures with partial results — when business rules, permissions, or absent data block progress, hand up the structured context so a human or coordinator can decide.

Escalation triggers should be concrete (policy gaps, threshold violations, no progress after attempts, explicit human requests) — never based on sentiment or a model's self-rated confidence score.

Test your routing instinct on a realistic agent failure.

Structured errors turn a dead end into a decision. Remember the four categories and their default routes:

• transient (isRetryable: true) → retry locally with backoff
• validation → fix the input, then retry
• business → respect the rule; escalate if blocked
• permission → stop; report or escalate the access gap

Always distinguish an access failure from a valid empty result. When propagating a failure, carry attempted_query and partial_results — never suppress silently and never abort the whole workflow on one failure. Generic errors block recovery; structured errors with a category and isRetryable enable it.