Structured Error Context
Failure type, attempted query, partial results, alternatives.
Why Errors Need Structure
In a multi-agent system, a subagent will eventually hit a failure: a database is down, a query returns nothing, a permission is denied. How that failure is reported decides whether the coordinator can recover intelligently or just gives up.
A generic status like "Operation failed" blocks recovery — the coordinator has no idea what to do next. A structured error context turns a dead end into a routing decision.
This lesson covers the four pillars of a good error context: failure type, attempted query, partial results, and alternatives.
The Generic-Error Anti-Pattern
Compare two error payloads coming back from a subagent or tool.
The generic version tells the coordinator nothing actionable. It can't decide whether to retry, ask the user for more input, or escalate. Silent suppression is even worse — the workflow continues as if data exists when it doesn't.
The structured version names what failed and why, which is the first step toward an intelligent next move.
# Anti-pattern: opaque, un-actionable
return {"isError": True, "message": "Operation failed"}
# Better: structured, routable
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"message": "Connection to orders DB timed out after 5s",
}All lessons in this course
- Clear Escalation Triggers
- Anti-Pattern: Sentiment & Confidence Scores
- Structured Error Context
- Local Recovery vs Escalation