Agent SDK reference - Python changedagent-sdk/python
Nearest release: v2.1.248, published 5 hours after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+10added
Lines−4removed
From line
1,901
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits62to this page, all time
The whole hunk
from line 1901, old and new numbered
/
from line 1901
19011901
19021902```python theme={null}
19031903class ResultError(ProcessError):
1904 subtype: str | None # for example "error_max_turns" or "error_during_execution"
1904 subtype: str | None # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
19051905 errors: list[str] # an empty list when the result message reported none
19061906 result: str | None
19071907 api_error_status: int | None
1908 terminal_reason: str | None # for example "max_turns" or "api_error"
1908 terminal_reason: str | None # "max_turns", "api_error", ...; check this before subtype
19091909 session_id: str | None
19101910 data: dict[str, Any] # the raw result message payload
19111911```
19121912
1913To tell failures apart, check `terminal_reason` before `subtype`. When the final request fails, such as on an API error, Claude Code reports `subtype` `"success"` with the cause in `terminal_reason`, for example `"api_error"`; when a limit you set ends the run, such as `max_turns` or `max_budget_usd`, it reports an `error_*` subtype.
1914
19131915### `CLIJSONDecodeError`
19141916
19151917Raised when JSON parsing fails.
from line 3387
33853387 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
33863388 )
33873389 # Catch ResultError before ProcessError, which it subclasses. Its message
3388 # carries the error text; branch on e.subtype or e.terminal_reason.
3390 # carries the error text. A failed final request, such as an API error,
3391 # arrives with subtype "success", so branch on terminal_reason first.
33893392 except ResultError as e:
3390 print(f"Query ended with an error result ({e.subtype}): {e}")
3393 if e.terminal_reason == "api_error":
3394 print(f"API request failed: {e}")
3395 else:
3396 print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
33913397 except ProcessError as e:
33923398 print(f"Process failed with exit code: {e.exit_code}")
33933399 except CLIJSONDecodeError as e:
No line in this hunk matches that.