# Exceptions 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. {% hint style="info" %} **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. {% endhint %} ### 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 | {% hint style="warning" %} 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. {% endhint %} ### Usage ```python 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}") ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mozilla.ai/api-reference/exceptions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.