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.

def AnyLLMError(
    self,
    message: str | None = None,
    original_exception: Exception | None = None,
    provider_name: 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).

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

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
Provider internal / network error	ProviderError	5xx responses, timeouts, connection errors

Note that ModelNotFoundError and InvalidRequestError are separate subclasses of AnyLLMError. A model-not-found error will not be caught by except InvalidRequestError. Catch ModelNotFoundError explicitly if you need to handle it.

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}")