The Anthropic SDK's exception hierarchy roots at AnthropicError and splits into two main branches: APIError for API failures (with APIStatusError for HTTP errors and specialized subclasses like RateLimitError), and APIConnectionError for transport failures like timeouts and overloads. RetryableError is a separate class that opts requests into automatic retry logic, allowing middleware to signal transient failures that should be retried up to max_retries before propagating to the caller.
The exception hierarchy in src/anthropic/_exceptions.py is rooted at AnthropicError(Exception), with APIError(AnthropicError) as the base for all API-related errors and APIStatusError(APIError) as the base for HTTP 4xx/5xx status errors.[1] APIError exposes a body property that holds the decoded JSON object if the API returned valid JSON, the raw response if the body is not valid JSON, or None if no response was associated with the error.[1] APIStatusError attempts to extract the error type field from a nested error key in the response body JSON, storing it as self.type (an ErrorType or None).[1]
The publicly exported exception names from src/anthropic/_exceptions.py (via __all__) are BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, and InternalServerError — notably excluding OverloadedError, RequestTooLargeError, ServiceUnavailableError, and DeadlineExceededError.[1] OverloadedError uses the non-standard HTTP status code 529, which is Anthropic's custom code indicating the API is overloaded.[1]
APIConnectionError defaults its message to "Connection error." and always sets body=None.[1] APITimeoutError inherits from APIConnectionError (not directly from APIStatusError) and uses a specific message directing users to Anthropic's long-requests documentation.[1] APIResponseValidationError defaults its message to "Data returned by API invalid for expected schema." when no custom message is provided.[1] APIWebhookValidationError extends APIError and is used for webhook validation failures, carrying no additional behavior beyond the base class.[1]
RetryableError is a special class rooted directly at AnthropicError that opts into the SDK's retry policy: raising it — for example from middleware — causes the current request attempt to be retried, subject to max_retries exhaustion, after which it propagates to the caller as-is.[1] Middleware is custom code inserted into the SDK's request pipeline to inspect or modify requests and responses; in the Anthropic Python SDK context, middleware can raise RetryableError to signal that a request attempt should be retried.
Sources