Error Categories
Transient, validation, business and permission errors.
Why Error Categories Matter
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.
The Shape of a Structured Error
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.
# A structured tool error returned to Claude
{
"isError": True,
"errorCategory": "transient", # transient | validation | business | permission
"isRetryable": True,
"message": "Upstream inventory service timed out after 5s",
"attempted_query": "SELECT stock FROM inventory WHERE sku='A-19'",
"partial_results": []
}