Agent SDK reference - Python changedagent-sdk/python
Nearest release: v2.1.247, published 5 hours before 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+29added
Lines−5removed
From line
1,855
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits62to this page, all time
### `ResultError`
The whole hunk
from line 1855, old and new numbered
/
from line 1855
18551855 """Base error for Claude SDK."""
18561856```
18571857
1858When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a plain `Exception` after yielding the final result message, not a `ClaudeSDKError` subclass.
1858When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a [`ResultError`](#resulterror) after yielding the final result message. Python Agent SDK versions before 0.2.140 raised a plain `Exception` that wasn't a `ClaudeSDKError` subclass.
18591859
18601860### `CLINotFoundError`
18611861
from line 1895
18951895 self.stderr = stderr
18961896```
18971897
1898### `ResultError`
1899
1900Raised after the final [`ResultMessage`](#resultmessage) when the Claude Code process exits because the run ended with an error result, such as a turn-limit error or an API error. `ResultError` subclasses `ProcessError`, so an existing `except ProcessError` handler also catches it. Its attributes carry the fields of that result message, so you can branch on why the run failed without parsing the message text. Requires Python Agent SDK 0.2.140 or later.
1901
1902```python theme={null}
1903class ResultError(ProcessError):
1904 subtype: str | None # for example "error_max_turns" or "error_during_execution"
1905 errors: list[str] # an empty list when the result message reported none
1906 result: str | None
1907 api_error_status: int | None
1908 terminal_reason: str | None # for example "max_turns" or "api_error"
1909 session_id: str | None
1910 data: dict[str, Any] # the raw result message payload
1911```
1912
18981913### `CLIJSONDecodeError`
18991914
19001915Raised when JSON parsing fails.
from line 3362
33473362
33483363### Error handling
33493364
3365This example catches [`ResultError`](#resulterror), which requires Python Agent SDK 0.2.140 or later.
3366
33503367```python theme={null}
33513368import asyncio
33523369
3353from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError
3370from claude_agent_sdk import (
3371 query,
3372 CLINotFoundError,
3373 ProcessError,
3374 ResultError,
3375 CLIJSONDecodeError,
3376)
33543377
33553378
33563379async def main():
from line 3384
33613384 print(
33623385 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
33633386 )
3387 # Catch ResultError before ProcessError, which it subclasses. Its message
3388 # carries the error text; branch on e.subtype or e.terminal_reason.
3389 except ResultError as e:
3390 print(f"Query ended with an error result ({e.subtype}): {e}")
33643391 except ProcessError as e:
33653392 print(f"Process failed with exit code: {e.exit_code}")
33663393 except CLIJSONDecodeError as e:
33673394 print(f"Failed to parse response: {e}")
3368 # A single-shot query() raises a plain Exception after yielding an error result
3369 except Exception as e:
3370 print(f"Query ended with an error result: {e}")
33713395
33723396
33733397asyncio.run(main())
No line in this hunk matches that.