[DOCS] Headless and Agent SDK docs do not explain error result payloads beyond subtype names

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

JSON/result handling for claude -p and the linked Agent SDK ResultMessage / SDKResultMessage error variants

Current Documentation

The headless docs currently describe JSON output in success-oriented terms only:

* json: structured JSON with result, session ID, and metadata This example returns a project summary as JSON with session metadata, with the text result in the result field:

The Agent SDK loop docs currently show error handling as subtype-only branching:

if isinstance(message, ResultMessage): if message.subtype == "success": print(message.result) else: print(f"Stopped: {message.subtype}")

The TypeScript reference lists the error-shape fields, but without prose explaining how callers should interpret them:

subtype: | "error_max_turns" | "error_during_execution" | "error_max_budget_usd" | "error_max_structured_output_retries"; ... is_error: boolean; ... errors: string[];

The Python reference similarly lists is_error, but the surrounding docs do not explain what a consumer should surface from an error result:

class ResultMessage: subtype: str ... is_error: bool ... result: str | None = None

What's Wrong or Missing?

Changelog v2.1.88 says:

Fixed SDK error result messages (error_during_execution, error_max_turns) to correctly set is_error: true with descriptive messages

The published docs still do not explain that error-payload contract clearly.

A. Headless JSON docs do not describe error-shaped results

The claude -p --output-format json docs explain the success case (result, session metadata, structured output), but do not show what callers receive when a run ends with error_max_turns or error_during_execution.

B. The loop docs encourage subtype-only handling

The main Agent SDK examples branch on message.subtype, but they do not explain that error variants also carry explicit error-state fields and descriptive error text. As written, the examples encourage printing only the subtype name.

C. Reference pages list fields without usage guidance

The TypeScript reference exposes is_error and errors, and the Python reference exposes is_error, but there is no prose that explains when those fields are populated, how they relate to the error subtypes, or what consumers should surface to end users instead of only logging the subtype.

Suggested Improvement

Add a short "error result payloads" section to the programmatic output docs that covers both CLI JSON output and Agent SDK result messages.

At minimum, document:

1. that error result variants set is_error: true
2. which fields callers should inspect on error results instead of assuming result is always present
3. where descriptive error text is surfaced for each documented API surface
4. a minimal error-aware example for both Python and TypeScript
5. that the existing result field is success-oriented and should not be treated as the universal place to read error text

The existing examples in the Agent SDK docs should also be updated to show error-aware handling instead of logging only message.subtype.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Primary CLI/SDK entry point for claude -p JSON output |
| https://platform.claude.com/docs/en/agent-sdk/agent-loop | Main result-handling guide currently shows subtype-only error handling |
| https://platform.claude.com/docs/en/agent-sdk/typescript | SDKResultMessage reference lists is_error and errors but not how to use them |
| https://platform.claude.com/docs/en/agent-sdk/python | ResultMessage reference lists is_error, but not how callers should surface error payloads |

Total scope: 4 pages affected

Source: Changelog v2.1.88

Changelog entry:

Fixed SDK error result messages (error_during_execution, error_max_turns) to correctly set is_error: true with descriptive messages