What you will be able to do
- Design the error payload a subagent returns so a coordinator can choose a recovery action
- Tell an access failure apart from a valid empty result and report each one differently
- Explain why hiding a failure as an empty success and halting the whole workflow over one failed source are both anti-patterns, and what to do instead
- Decide which failures a subagent should retry on its own and which it should send to the coordinator
- Annotate a final synthesis with which findings are well supported and which topics have gaps
Key concept
Structured error propagation — A coordinator knows about a failure only through what the subagent reports. Subagents therefore fix transient failures themselves and send up anything they cannot fix as structured context: what failed, what was tried, what was recovered and what else could work. The coordinator then has enough to choose a recovery instead of guessing.
1.The coordinator recovers from what it is told
In a multi-agent system, an error is only useful if it reaches the agent that can act on it. In a Hub-and-spoke coordinator design, the coordinator sends work to subagents and builds its answer from what they return. It never sees their tool calls, retries or raw responses. Each subagent works in its own context, and only its final message goes back to the parent. That isolation is what keeps the coordinator's context clean, and it also means the coordinator learns about a failure only if the subagent describes it.
Take a research coordinator that sends four subagents to cover regulatory filings, news, patents and analyst reports. Suppose the patents subagent hits a database that refuses connections. The coordinator's next move depends entirely on that subagent's final message. It could retry later, send the work to another source, narrow the question, or go ahead and flag the gap. If the message says what happened, the coordinator can pick one. If it only says that something went wrong, the coordinator has nothing to choose with.
Agents handle failures well when someone tells them about the failure. Anthropic's experience building its multi-agent research system was that telling an agent a tool is failing and letting it adapt works well. A coordinator is an agent too, so the same applies one level up. A subagent's error report is the tool result the coordinator reasons from.
Checkpoint 1 of 9· Check yourself
A research coordinator sends a patents subagent to search a patent database. The database refuses connections. The subagent retries twice and then returns only: "Patent search could not be completed." What does the coordinator have to decide its recovery from?
Each subagent runs in its own context, and only its final message reaches the parent. A vague final message therefore leaves the coordinator with nothing to base a choice on: it can't tell whether to retry, reroute, narrow the question or flag the gap.
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”Source: code.claude.com
2.Structured error context instead of a generic status
A generic status like "search unavailable" says that something failed but not why, what was tried, or what can still be saved. A coordinator that gets only that string can't tell a ten-second network blip from an expired credential. It doesn't know whether half the results already arrived, and it can't see any route other than retrying the same call. The useful details existed inside the subagent and were dropped on the way up.
At the level of a single tool, the basic pattern is to report the error instead of crashing, with a flag that marks it as an error:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}That flag and message tell an agent what failed during one call. A subagent reporting to a coordinator has to say more, because the coordinator is deciding about a whole piece of work, not one call. The tool-level categories and retryability flags from Error categories and isRetryable metadata become one field in a larger report. That report should contain:
- Failure type: the category, such as a timeout, an authentication failure, a rate limit or an invalid query, so the coordinator knows whether retrying could help
- What was attempted: the exact query or action and the source it went to, so the coordinator doesn't send the same doomed request again
- Partial results: anything gathered before the failure, such as three of four pods' logs or the first 40 of 200 filings, so finished work isn't thrown away
- Possible alternatives: a read replica, a different index, a broader date range or a second provider that could fill the gap
Other report designs look reasonable but leave out the next step. A fixed code like UNAVAILABLE is easy for code to branch on, but it is the generic string again in capitals. The coordinator can branch on it without knowing which branch to take. A numeric code with the raw message and a severity rating describes the failure without saying what was tried or saved. Retry counts, timestamps and subagent IDs are monitoring data. They help a human debug later but don't help the coordinator recover now. Writing full details to a log and keeping the coordinator's message short puts the information where the coordinator can't read it. Sending the subagent's whole reasoning trace and raw output goes too far the other way: it floods the coordinator's context, which is the problem context isolation was meant to prevent.
Checkpoint 2 of 9· Fill the gap
A tool call to the weather service failed. Which field name, set to true, tells the agent that this tool_result is an error and not a successful answer?
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
" ? ": true
}
]
}Setting is_error: true marks the tool_result as a failure, and the content names the cause. Without the flag, the error text would look like an ordinary result. This is how a single tool reports an error at the tool level, and it is the basis for the larger report a subagent sends up to its coordinator.
Source: platform.claude.comCheckpoint 3 of 9· Check yourself
A filings subagent's database times out partway through its work. You are designing the final message it returns. Which payload best lets the coordinator choose how to recover?
The coordinator needs to know whether a retry could help, what was already tried, what was already saved and what else could work. Only the third payload gives it all four. A fixed status code is just the generic string again. A raw error with a severity rating describes the failure but not what was tried or saved. Retry counts, timestamps, IDs and log files are monitoring data the coordinator can't use to recover.
“include only the fields Claude needs to reason about its next step. Bloated responses waste context”Source: platform.claude.com
Checkpoint 4 of 9· Exam question
A document-search subagent hits an authentication error against a knowledge base and simply returns the string 'search unavailable' to the coordinator. The coordinator has no other information to act on. What is the primary problem with this design, and what should replace it?
Correct answer: A — The string omits why the search failed; return an error category, the attempted query, and the partial results gathered
- A. Correct. A bare 'search unavailable' hides the cause of the failure, what was attempted and what was already found. The coordinator needs those details to choose between retrying, rerouting to another source or continuing with partial coverage.
- B. An authentication error is a persistent condition, so retrying with backoff will not clear it. An attempt count also says nothing about the cause, the query or any partial results, so the coordinator still cannot choose a recovery path.
- C. A fixed status code such as UNAVAILABLE is easier to branch on but carries no more information than the current string. The coordinator still cannot tell an authentication failure from other outages and gets no query context or partial results.
- D. Writing the auth error to the subagent's own log helps later debugging, but the coordinator never sees it. The coordinator still receives a short, uninformative message and has nothing to act on, which is the failure described.
Checkpoint 5 of 9· Exam question
A team is designing the error payload that subagents return to a coordinator when a tool call fails. Which set of fields best supports intelligent coordinator recovery decisions?
Correct answer: A — Failure category, the attempted action, partial results gathered, and suggested alternative approaches
- A. Correct. A failure category, the attempted action, salvageable partial results and suggested alternatives are structured fields. They let the coordinator decide whether to retry, reuse what was gathered, or try a different path.
- B. A code, message, tool name and severity describe that something broke, but they give the coordinator no partial results to reuse and no alternative approaches to choose from. It can only retry or give up, not recover intelligently.
- C. Retry count, timing and an identifier are bookkeeping metadata. They say nothing about why the call failed, what was attempted, or what was already gathered, so the coordinator cannot choose between retrying, adapting or escalating.
- D. Reasoning traces, raw output and logs are unstructured and verbose. The coordinator would have to parse free text to work out the failure type and what is salvageable, and the payload still offers no alternative approaches.
Sources3
3.Access failures, empty results and silent suppression
"No results" can mean two opposite things, and the coordinator needs to know which. The point is covered at tool level in Access failure vs valid empty result. Across agents the stakes are higher. A query that ran and matched nothing is a finding: the discontinued SKU really has no rows, and the narrow fact pattern really matches zero cases. A query that never completed, because it timed out, hit an exhausted connection pool or used an expired key, says nothing about whether matches exist. A timeout is especially ambiguous because the request may have run on the server. Each one needs its own report: an empty result reported as a success with zero items, and an access failure reported as an error with the structured context described in the previous section.
Silent suppression turns a gap in coverage into false evidence. An empty list marked as a success tells the coordinator that the source was checked and held nothing. The coordinator then reasons correctly from a false input and states that no relevant filings exist, when in fact nobody looked. This can't be repaired downstream. A validation pass on an empty list can't tell a real zero from a hidden failure, because the only point where that difference was visible was inside the subagent when the call failed. Report the access failure as an error at that point.
The opposite reaction is also a mistake: ending the whole workflow because one source failed. An expired filings key doesn't make the news, patent and analyst subagents' results any less valid. Throwing them away wastes completed work, and restarting from scratch is expensive. Anthropic's research system resumes from where the agent was when the error happened, because restarts are expensive and frustrating for users. One source failing is a reason to recover or flag a gap, not to stop.
Both reactions are anti-patterns, and they fail in opposite directions. Silently suppressing an error produces an answer that looks complete and is wrong, because the failure is invisible to everyone downstream. Terminating the entire workflow on a single failure produces no answer at all, although most of the work was sound. Each one is tempting for a reason: suppression keeps the dashboard green, and termination feels cautious. The way out of both is the same. The subagent reports the failure honestly, with its type, the attempted query, partial results and alternatives. The coordinator then keeps the valid results, recovers what it can, and marks what it could not cover.
Checkpoint 6 of 9· Match them up
Match each situation in a four-source research pipeline to the right way to handle it.
Tap a term, then the definition that fits it.
An empty result from a query that completed is evidence. A query that never completed says nothing about whether matches exist, so it must be reported as an error. Hiding that failure as an empty success creates false coverage. Stopping everything over one failed source throws away valid work. The right response is to report the error and let the coordinator recover or flag the gap.
“When a tool raises an error, send the error message back with is_error: true instead of crashing.”Source: platform.claude.com
Checkpoint 7 of 9· Exam question
A regulatory-filings subagent cannot reach its data provider because the provider's API key expired. Instead of surfacing the failure, the subagent returns an empty findings list with status 'success' so the pipeline continues cleanly. The coordinator later synthesizes a report claiming full regulatory coverage. What went wrong?
Correct answer: A — The subagent returned a completed result for a request it could not make, so the coordinator never learned the source was unavailable
- A. Correct. The subagent could not reach the provider but reported the call as a finished success with no findings. That hid the access failure from the coordinator, which had no signal that coverage was incomplete and so reported full coverage.
- B. Retrying cannot fix an expired API key. Every attempt would fail the same way until the credential is renewed, so a longer retry window would not have fetched the data. The real defect is that the failure was reported as a success.
- C. The coordinator received a result marked successful, so a generic validation pass would not show that the empty list came from an access failure. The defect lies in the subagent's mislabeled status, and reporting the failure accurately is what gives the coordinator the signal it needs.
- D. The other subagents' results are unaffected by the expired key and remain valid. Discarding them is not the remedy. The subagent should report the failure explicitly so the coordinator can proceed and disclose the gap in the provider's coverage.
4.Recover locally, propagate what's left
The subagent that hits a failure is in the best position to fix it, so it should try first. A rate limit, an overloaded server or a dropped connection usually clears after a short, limited number of retries with backoff. The subagent has the query, the credentials and the partial results in its own context, so it can retry cheaply. Sending every short-lived failure up to the coordinator would fill the coordinator's context with problems that would have fixed themselves. The Agent SDK sorts failures the same way for its own subagent retries, using an error_category field:
| error_category | Likely to clear on retry? | Handled by |
|---|---|---|
| rate_limit | Yes, after a delay | Subagent retries locally with backoff |
| overloaded | Yes, after a delay | Subagent retries locally with backoff |
| server_error | Often | Subagent retries a limited number of times, then reports up |
| authentication_failed | No | Reported to coordinator right away |
| cloud_credential_error | No | Reported to coordinator right away |
| unknown | Can't tell | Limited retries, then reported up with full context |
Retries need a limit and must match the failure type. Single tool calls already work this way: an agent given an invalid tool request retries 2–3 times with corrections and then gives up. Backoff makes no sense for an authentication failure, because waiting won't fix a credential. Retrying it only delays the report the coordinator needs. Once local recovery is used up, or never applied, the subagent sends up what remains. That report includes each attempt it made and why it failed, the partial results it is keeping, and the alternatives it can see. A retry count alone isn't enough. It shows effort, not what the coordinator should do next.
With that report, the coordinator has real choices and doesn't need to stop the run. It can send a follow-up asking the same subagent to try the suggested replica. It can send the gap to another subagent that has a different source. Or it can accept the partial results and continue with the gap noted. This combines retry logic in code with an agent that adapts to what it is told. The subagent handles what it can fix, and the coordinator handles what the subagent can't.
Checkpoint 8 of 9· Check yourself
Your news subagent gets an overloaded error from its search provider on the first call. After a second query works, the next call returns authentication_failed. It already holds 12 articles. Which retry policy should it follow?
An overload usually clears after a short wait, so the subagent should handle it with a few retries of its own. Waiting can't fix a credential, so the authentication failure goes to the coordinator immediately. That report needs to include what was tried, the partial results and the alternatives. A retry count alone shows effort but doesn't tell the coordinator what to do next.
“If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user.”Source: platform.claude.com
5.Coverage annotations in the final synthesis
Errors that were reported correctly still need to show up in the final answer. Otherwise the reader of the synthesis makes the same mistake a coordinator would make with a suppressed failure. A report that just leaves out the patents section, without saying why, looks the same as one where patents were searched and nothing was found. Coverage annotations fix this by marking two things on the output:
- Support per finding: whether a claim is backed by several independent sources, by one source, or only by partial results from a source that failed partway
- Gaps per topic: which topic areas are thin or missing because a source was unavailable, naming the source, the reason, and what was tried
An annotated report might read: "Regulatory filings: well supported by 14 filings from two providers. Patent landscape: gap. The patent database rejected our credentials and a fallback search of a public index returned partial results for 2024 only, so findings before 2024 are unverified." Someone reading that knows exactly how far to trust each section and what to fill in by hand.
Coverage annotations need room in the output format from the start. A synthesis schema where every topic must contain findings pushes the model to fill gaps with weak material instead of marking them. Give each topic a support level and an optional gap note. Then a missing source becomes a field that is filled in, not a hole that someone has to notice.
Usually not. It should publish what it has, mark findings backed by the healthy sources as well supported, mark the partial source's findings as limited, and name the missing topic as a gap with the failure reason and what was attempted. Holding the report back throws away completed work. Publishing without annotations hides the gap.
Checkpoint 9 of 9· Check yourself
In a four-source research pipeline, the patent database sometimes rejects credentials while the other sources keep working. How should the coordinator's synthesis output schema handle each topic so the final report stays trustworthy?
The output format needs room for gaps from the start. Then a missing source shows up as a filled-in field, not a hole. If every topic must have findings, the model fills gaps with weak material. Leaving the topic out looks the same as searching and finding nothing. A separate log puts the gap where the report's reader can't see it.
“Match schema to task. If the task might not have all the information your schema requires, make those fields optional.”Source: code.claude.com
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ The coordinator recovers from what it is told“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Key concept - 2.
“letting the agent know when a tool is failing and letting it adapt works surprisingly well.”
↩︎ The coordinator recovers from what it is told“restarts are expensive and frustrating for users.”
↩︎ Access failures, empty results and silent suppression“We combine the adaptability of AI agents built on Claude with deterministic safeguards like retry logic and regular checkpoints.”
↩︎ Recover locally, propagate what's left“When errors occur, we can't just restart from the beginning: restarts are expensive and frustrating for users.”
↩︎ Exam trap 3 - 3.
“When a tool raises an error, send the error message back with is_error: true instead of crashing.”
↩︎ Structured error context instead of a generic status“Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation.”
↩︎ Structured error context instead of a generic status“Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation.”
↩︎ Exam trap 1“When a tool raises an error, send the error message back with is_error: true instead of crashing.”
↩︎ Checkpoint - 4.
“is_error (optional): Set to true if the tool execution resulted in an error.”
↩︎ Access failures, empty results and silent suppression“If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user.”
↩︎ Recover locally, propagate what's left“Claude will then incorporate this error into its response to the user.”
↩︎ Coverage annotations in the final synthesis“is_error (optional): Set to true if the tool execution resulted in an error.”
↩︎ Exam trap 2 - 5.https://code.claude.com/docs/en/agent-sdk/typescriptOfficial docs
“The values are rate_limit, overloaded, authentication_failed, server_error, cloud_credential_error, and unknown.”
↩︎ Recover locally, propagate what's left“The values are rate_limit, overloaded, authentication_failed, server_error, cloud_credential_error, and unknown.”
↩︎ Exam trap 4 - 6.
“so the agent can send it follow-up messages.”
↩︎ Recover locally, propagate what's left - 7.
“If the task might not have all the information your schema requires, make those fields optional.”
↩︎ Coverage annotations in the final synthesis“Match schema to task. If the task might not have all the information your schema requires, make those fields optional.”
↩︎ Checkpoint
Also cited
“include only the fields Claude needs to reason about its next step. Bloated responses waste context”
↩︎ Checkpoint