[DOCS] `sub-agents.md` API-error section only covers subagents cut off after producing output; v2.1.200 added the "before any text" case
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/sub-agents
Section/Topic
The "API errors in subagents" section near the end of sub-agents.md, immediately before the "Common patterns" heading.
Current Documentation
sub-agents.md:740-755 documents the v2.1.199 behavior in the "API errors in subagents" section:
As of v2.1.199, a subagent whose run ends on an API error, such as a usage limit or a repeated server error, reports that failure back to Claude instead of returning the error text as if it were the subagent's findings. What Claude receives depends on where the subagent ran: Foreground: if a rate limit, overload, or server error cuts off a subagent that already produced output, the Agent tool returns that partial output with a note that the subagent was cut off and didn't finish its task. Otherwise the tool call fails with Agent terminated early due to an API error, followed by the error detail. Background: the subagent is marked failed, and the message Claude receives when it ends names the API error and includes the subagent's last output, so partial work isn't lost.
errors.md:227 documents the corresponding foreground error message:
A subagent's API request failed terminally, for example because a usage limit was reached or retries for a server error ran out, so the subagent stopped before finishing its task. This message requires Claude Code v2.1.199 or later; before then the API error text was returned to Claude as if it were the subagent's result.
What's Wrong or Missing?
A. The "before any text" case has no docs entry
The v2.1.200 changelog says:
Fixed subagents cut off by a rate limit before producing any text output returning an empty result instead of failing cleanly
Before v2.1.200, a rate limit that hit a subagent before it produced any text returned an empty result, so the parent saw a successful subagent that produced nothing. The "Foreground" bullet in sub-agents.md covers the "already produced output" path (partial output with a cut-off note) but the "no output at all" path is only addressed indirectly: the errors.md entry that names Agent terminated early due to an API error covers the v2.1.199 case where the error has text to report, not the v2.1.200 case where the rate limit fires before any output exists.
B. The distinction between "partial output" and "no output at all" is not made
After v2.1.200, "partial output + cut-off note" and "no output + terminal error" are two distinct outcomes from a foreground subagent. The docs present the partial-output path and the error path side by side but never say what separates them. A reader who wants to know whether their subagent will return partial work or fail cleanly cannot answer that from the current page.
C. The errors.md reference page does not list the v2.1.200 message
errors.md catalogues each foreground error message a user might see and explains when it appears. The new v2.1.200 foreground error message — for the rate-limit-before-any-output case — is not listed there, so users hitting it have no in-page anchor.
Suggested Improvement
Update the "Foreground" bullet in sub-agents.md to split the path into two:
* Foreground: if a rate limit, overload, or server error cuts off a subagent that already produced text output, the Agent tool returns that partial output with a note that the subagent was cut off and didn't finish its task. If the rate limit hits before the subagent produces any output, the Agent tool call fails with Agent terminated early due to an API error, followed by the error detail (added in v2.1.200; before then the tool returned an empty result that looked like success).
Add the corresponding entry to errors.md's catalogue of foreground error messages, noting the v2.1.200 requirement and the v2.1.199 / v2.1.200 distinction between "partial output kept" and "no output kept".
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 740-755 | "API errors in subagents" section, "Foreground" bullet |
| https://code.claude.com/docs/en/errors | 227-238 | Foreground subagent error message catalogue |
Total scope: 2 pages, one page already documented the v2.1.199 path; the v2.1.200 "before any output" path is missing from both.
The release note for this fix appears in v2.1.200 (July 3, 2026).