Exceptions

Unified exception hierarchy for all providers

any-llm provides a unified exception hierarchy so you can handle errors consistently regardless of which provider is being used. When unified exceptions are enabled, provider-specific SDK errors are automatically mapped to the appropriate any-llm exception type.

Opt-in Feature: Unified exception handling is opt-in. Set the ANY_LLM_UNIFIED_EXCEPTIONS=1 environment variable to enable automatic conversion from provider-specific exceptions.

Exception Hierarchy

All exceptions inherit from AnyLLMError:

AnyLLMError
├── AuthenticationError
├── BatchNotCompleteError
├── ContentFilterError
├── ContentFilterFinishReasonError
├── ContextLengthExceededError
├── GatewayTimeoutError
├── InsufficientFundsError
├── InvalidRequestError
├── LengthFinishReasonError
├── MissingApiKeyError
├── ModelNotFoundError
├── ProviderError
├── RateLimitError
├── UnsupportedParameterError
├── UnsupportedProviderError
├── UpstreamProviderError
└── _FinishReasonError

AnyLLMError

Base exception for all any-llm errors. All custom exceptions in any-llm inherit from this class. It preserves the original exception for debugging while providing a unified interface. The structured HTTP fields are populated best-effort by :func:any_llm.utils.exception_handler.convert_exception from whatever the provider SDK exposed, so a consumer can classify a failure without reaching into original_exception and coupling to a specific SDK's attribute layout. Any field a provider does not report stays None, and a non-HTTP failure (timeout, connection error) reports status_code=None.

def AnyLLMError(
    self,
    message: str | None = None,
    original_exception: Exception | None = None,
    provider_name: str | None = None,
    *,
    status_code: int | None = None,
    code: str | None = None,
    param: str | None = None,
    error_type: str | None = None,
) -> None

Attribute	Type	Description
message	str	Human-readable error message.
original_exception	Exception | None	The original SDK exception that triggered this error.
provider_name	str | None	Name of the provider that raised the error (if available).
status_code	int | None	HTTP status the provider returned.
code	str | None	Provider-specific error code from the response body.
param	str | None	Request field the provider flagged as the cause.
error_type	str | None	Provider-specific error category, such as "invalid_request_error".

The string representation includes the provider name when available: "[openai] Rate limit exceeded".

Coverage of the four HTTP metadata fields varies by provider, so treat every one as optional.

Provider Errors

RateLimitError

Raised when the API rate limit is exceeded.

class RateLimitError(AnyLLMError): ...

Default message: "Rate limit exceeded"

AuthenticationError

Raised when authentication with the provider fails (invalid or missing API key).

class AuthenticationError(AnyLLMError): ...

Default message: "Authentication failed"

InvalidRequestError

Raised when the request to the provider is malformed or contains invalid parameters.

class InvalidRequestError(AnyLLMError): ...

Default message: "Invalid request"

ProviderError

Raised when the provider encounters an internal error (5xx-class errors).

class ProviderError(AnyLLMError): ...

Default message: "Provider error"

ContentFilterError

Raised when content is blocked by the provider's safety filter.

class ContentFilterError(AnyLLMError): ...

Default message: "Content blocked by safety filter"

ModelNotFoundError

Raised when the requested model is not found or not available.

class ModelNotFoundError(AnyLLMError): ...

Default message: "Model not found"

ContextLengthExceededError

Raised when the input exceeds the model's maximum context length.

class ContextLengthExceededError(AnyLLMError): ...

Default message: "Context length exceeded"

Configuration Errors

MissingApiKeyError

Raised when a required API key is not provided via the parameter or environment variable.

class MissingApiKeyError(AnyLLMError):
    def __init__(self, provider_name: str, env_var_name: str) -> None: ...

Attribute	Type	Description
provider_name	str	Name of the provider requiring the key.
env_var_name	str	Environment variable name that was checked.

Example message: "No openai API key provided. Please provide it in the config or set the OPENAI_API_KEY environment variable."

UnsupportedProviderError

Raised when an unsupported provider is specified.

class UnsupportedProviderError(AnyLLMError):
    def __init__(self, provider_key: str, supported_providers: list[str]) -> None: ...

Attribute	Type	Description
provider_key	str	The unsupported provider key that was specified.
supported_providers	list[str]	List of valid provider keys.

UnsupportedParameterError

Raised when a parameter is not supported by the provider.

class UnsupportedParameterError(AnyLLMError):
    def __init__(self, parameter_name: str, provider_name: str, additional_message: str | None = None) -> None: ...

Attribute	Type	Description
parameter_name	str	The unsupported parameter name.
provider_name	str	Name of the provider (also accessible via the inherited provider_name attribute).

Common Scenarios

The table below maps typical error conditions to the unified exception that any-llm raises. Use this to decide which exceptions to catch in your application.

Scenario	Exception	Example Trigger
Invalid or unknown model name	ModelNotFoundError	model="not-a-real-model"
Bad or missing API key	AuthenticationError	Invalid api_key parameter
Too many requests	RateLimitError	Provider rate limit exceeded
Input too long	ContextLengthExceededError	Exceeding the model's context window
Malformed request parameters	InvalidRequestError	Invalid parameter values
Content blocked by safety filter	ContentFilterError	Harmful or policy-violating content
Out of credits or quota	InsufficientFundsError	402 responses
Bad gateway upstream of the provider	UpstreamProviderError	502 responses
Provider timed out at its gateway	GatewayTimeoutError	504 responses
Provider internal / network error	ProviderError	Other 5xx responses, timeouts, connection errors

Every exception above is a separate subclass of AnyLLMError, not of each other. A model-not-found error will not be caught by except InvalidRequestError, and InsufficientFundsError, UpstreamProviderError, and GatewayTimeoutError will not be caught by except ProviderError. Catch AnyLLMError if you want all of them.

How the Exception Type Is Chosen

status_code decides the type wherever it is unambiguous, because it is what the provider actually returned:

Status	Exception
401	AuthenticationError
402	InsufficientFundsError
403	AuthenticationError
404	ModelNotFoundError
429	RateLimitError
502	UpstreamProviderError
504	GatewayTimeoutError
other 5xx	ProviderError

A 400 or 422 means the request was rejected but not why, so the error message decides between the specific causes that carry no status of their own (ContextLengthExceededError, ContentFilterError, or a provider that reports a bad key as a 400), falling back to InvalidRequestError. When there is no status at all, or the status is not one of those listed above (for example 409 or 413), the message decides on its own.

One consequence worth noting: a 5xx is always a provider fault, even when its body happens to mention something like a content policy.

Usage

from any_llm import completion
from any_llm.exceptions import (
    AnyLLMError,
    AuthenticationError,
    ContextLengthExceededError,
    InvalidRequestError,
    ModelNotFoundError,
    RateLimitError,
)

try:
    response = completion(
        model="gpt-4.1-mini",
        provider="openai",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except ModelNotFoundError as e:
    print(f"Model not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited by {e.provider_name}: {e.message}")
    # Access the original provider exception for details
    print(f"Original: {e.original_exception}")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except InvalidRequestError as e:
    print(f"Invalid request: {e.message}")
except ContextLengthExceededError as e:
    print(f"Input too long: {e.message}")
except AnyLLMError as e:
    # Catch-all for any other any-llm error
    print(f"Error: {e}")