Principle:Langchain ai Langgraph SDK Error Handling
| Attribute | Value |
|---|---|
| Type | Principle |
| Knowledge Sources | LangGraph |
| Domains | SDK, Error_Handling, API_Communication |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
SDK error handling provides a structured exception hierarchy that maps HTTP status codes and network failures to specific, typed Python exceptions, enabling precise error handling when communicating with the LangGraph API server.
Description
The LangGraph Python SDK defines a comprehensive error hierarchy rooted in `LangGraphError`, with `APIError` as the base class for all API-related exceptions. `APIError` inherits from both `httpx.HTTPStatusError` (for compatibility with the httpx HTTP client ecosystem) and `LangGraphError` (for LangGraph-specific error handling).
The hierarchy maps standard HTTP status codes to dedicated exception classes:
- `BadRequestError` (400) -- The request was malformed or contained invalid parameters.
- `AuthenticationError` (401) -- Authentication credentials are missing or invalid.
- `PermissionDeniedError` (403) -- The authenticated user lacks permission for the requested operation.
- `NotFoundError` (404) -- The requested resource (thread, run, assistant) does not exist.
- `ConflictError` (409) -- A resource conflict occurred, such as concurrent modification.
- `UnprocessableEntityError` (422) -- The request is well-formed but semantically invalid.
- `RateLimitError` (429) -- The client has exceeded the rate limit.
- `InternalServerError` (500+) -- A server-side failure occurred.
Network-level failures are represented by `APIConnectionError` (general connectivity issues) and its subclass `APITimeoutError` (request timeouts). Response schema violations raise `APIResponseValidationError`.
Each `APIStatusError` instance provides structured access to the `status_code`, `response` object, `request_id` header, and parsed error fields (`code`, `param`, `type`) extracted from the JSON response body. Helper functions handle response body decoding (with `orjson` fallback to raw string) and status-to-exception mapping.
Usage
Wrap SDK client calls in try/except blocks, catching specific error classes for targeted handling. Catch `NotFoundError` to handle missing resources gracefully, `AuthenticationError` to trigger re-authentication flows, `RateLimitError` to implement backoff strategies, and `APIConnectionError` for network resilience. Use the base `APIError` class as a catch-all for any API communication failure.
Theoretical Basis
The SDK error hierarchy implements the exception translation pattern from distributed systems design: low-level HTTP status codes and network errors are translated into domain-specific exception types that communicate intent rather than transport details. This shields application code from the specifics of the HTTP protocol while preserving the ability to handle different failure modes distinctly.
The multiple inheritance from `httpx.HTTPStatusError` implements the adapter pattern, allowing LangGraph SDK exceptions to be caught by both LangGraph-specific handlers and generic httpx error handlers, maximizing interoperability with existing HTTP client error handling code.
The structured error body parsing (extracting `code`, `param`, `type` from JSON responses) follows the rich error context principle: providing machine-readable error metadata alongside human-readable messages enables automated error handling, logging, and diagnostics without string parsing.