Implementation:BerriAI Litellm Exception Mapping

Knowledge Sources	BerriAI/litellm - litellm/litellm_core_utils/exception_mapping_utils.py, BerriAI/litellm - litellm/exceptions.py
Domains	LLM Integration, Error Management, Exception Design
Last Updated	2026-02-15

Overview

Concrete tool for mapping provider-specific LLM errors to a unified OpenAI-compatible exception hierarchy, provided by the litellm Python package via the exception_type() function in litellm/litellm_core_utils/exception_mapping_utils.py and the exception classes in litellm/exceptions.py.

Description

The exception_type() function is the central exception mapping engine in LiteLLM. It receives a raw exception from any provider handler, inspects its status code, error message, and type, and raises the corresponding LiteLLM canonical exception. The canonical exceptions are defined in litellm/exceptions.py and extend both the OpenAI SDK exception classes and LiteLLM-specific classes, ensuring compatibility with code written for the OpenAI SDK.

Supporting utilities include ExceptionMappingUtils (static methods for detecting rate-limit and context-window errors via string heuristics), get_error_message() (for extracting nested error messages from provider responses), and extract_and_raise_litellm_exception() (for re-raising LiteLLM exceptions from proxy error strings).

Usage

The exception_type() function is called internally by litellm.completion() and litellm.acompletion() when a provider raises an error. Application code catches the resulting canonical exceptions (e.g., litellm.RateLimitError, litellm.AuthenticationError).

Code Reference

Source Location:

• exception_type(): litellm/litellm_core_utils/exception_mapping_utils.py, lines 232-2415
• Exception classes: litellm/exceptions.py, lines 1-1017

Signature (exception_type):

def exception_type(
    model,
    original_exception,
    custom_llm_provider,
    completion_kwargs={},
    extra_kwargs={},
):
    """Maps an LLM Provider Exception to OpenAI Exception Format"""

Signature (extract_and_raise_litellm_exception):

def extract_and_raise_litellm_exception(
    response: Optional[Any],
    error_str: str,
    model: str,
    custom_llm_provider: str,
):
    """
    Covers scenario where litellm sdk calling proxy.
    Enables raising the special errors raised by litellm,
    eg. ContextWindowExceededError.
    """

Key Exception Classes:

class AuthenticationError(openai.AuthenticationError):
    def __init__(self, message, llm_provider, model,
                 response=None, litellm_debug_info=None,
                 max_retries=None, num_retries=None):
        self.status_code = 401

class NotFoundError(openai.NotFoundError):
    def __init__(self, message, model, llm_provider,
                 response=None, litellm_debug_info=None,
                 max_retries=None, num_retries=None):
        self.status_code = 404

class BadRequestError(openai.BadRequestError):
    def __init__(self, message, model, llm_provider,
                 response=None, litellm_debug_info=None,
                 max_retries=None, num_retries=None, body=None):
        self.status_code = 400

class ContextWindowExceededError(BadRequestError):
    def __init__(self, message, model, llm_provider,
                 response=None, litellm_debug_info=None):
        self.status_code = 400

class RateLimitError(openai.RateLimitError):
    def __init__(self, message, llm_provider, model,
                 response=None, litellm_debug_info=None,
                 max_retries=None, num_retries=None):
        self.status_code = 429

class Timeout(openai.APITimeoutError):
    def __init__(self, message, model, llm_provider,
                 litellm_debug_info=None, max_retries=None,
                 num_retries=None, headers=None,
                 exception_status_code=None):
        self.status_code = exception_status_code or 408

class ContentPolicyViolationError(BadRequestError):
    def __init__(self, message, model, llm_provider,
                 response=None, litellm_debug_info=None,
                 provider_specific_fields=None, body=None):
        self.status_code = 400

class PermissionDeniedError(openai.PermissionDeniedError):
    def __init__(self, message, llm_provider, model,
                 response, litellm_debug_info=None,
                 max_retries=None, num_retries=None):
        self.status_code = 403

class UnprocessableEntityError(openai.UnprocessableEntityError):
    def __init__(self, message, model, llm_provider,
                 response, litellm_debug_info=None,
                 max_retries=None, num_retries=None):
        self.status_code = 422

Import:

import litellm
from litellm.exceptions import (
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    ContextWindowExceededError,
    ContentPolicyViolationError,
    Timeout,
    NotFoundError,
    PermissionDeniedError,
)
from litellm.litellm_core_utils.exception_mapping_utils import exception_type

I/O Contract

Inputs (exception_type)

Parameter	Type	Description
model	str	The model that was targeted when the error occurred.
original_exception	Exception	The raw exception raised by the provider SDK or HTTP client.
custom_llm_provider	str	The resolved provider name (e.g., "openai", "anthropic", "azure").
completion_kwargs	dict	The keyword arguments passed to the original completion() call. Used to enrich error context.
extra_kwargs	dict	Additional keyword arguments for error context and metadata.

Outputs

Output	Type	Description
Raised exception	A litellm exception class	The function always raises a canonical LiteLLM exception (e.g., litellm.RateLimitError, litellm.AuthenticationError, litellm.BadRequestError). It does not return a value.

Exception Metadata Fields

Field	Type	Description
status_code	int	The HTTP status code (e.g., 400, 401, 429, 500).
message	str	The formatted error message, prefixed with the exception type (e.g., "litellm.RateLimitError: ...").
llm_provider	str	The provider that raised the original error.
model	str	The model being called when the error occurred.
litellm_debug_info	Optional[str]	Additional debugging context.
max_retries	Optional[int]	The configured maximum retry count.
num_retries	Optional[int]	The number of retries attempted before this exception was raised.

Usage Examples

Catching unified exceptions across providers:

import litellm

try:
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except litellm.AuthenticationError as e:
    print(f"Auth failed for {e.model} on {e.llm_provider}: {e.message}")
except litellm.RateLimitError as e:
    print(f"Rate limited (status {e.status_code}): {e.message}")
    # Implement backoff logic
except litellm.ContextWindowExceededError as e:
    print(f"Context too long for {e.model}: {e.message}")
    # Truncate messages and retry
except litellm.Timeout as e:
    print(f"Request timed out: {e.message}")
except litellm.BadRequestError as e:
    print(f"Bad request ({e.status_code}): {e.message}")

Handling errors uniformly across providers:

import litellm

models = ["gpt-4", "anthropic/claude-3-opus-20240229", "azure/my-deployment"]

for model in models:
    try:
        response = litellm.completion(
            model=model,
            messages=[{"role": "user", "content": "Hello!"}],
        )
    except litellm.RateLimitError as e:
        # Same exception type regardless of provider
        print(f"Rate limited on {e.llm_provider}: retries={e.num_retries}")
    except litellm.BadRequestError as e:
        print(f"Bad request on {e.llm_provider}: {e.message}")

Accessing exception metadata:

import litellm

try:
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": "x" * 1000000}],
    )
except litellm.ContextWindowExceededError as e:
    print(f"Status code: {e.status_code}")       # 400
    print(f"Provider: {e.llm_provider}")          # "openai"
    print(f"Model: {e.model}")                    # "gpt-4"
    print(f"Debug info: {e.litellm_debug_info}")  # Additional context

Related Pages

• Principle:BerriAI_Litellm_Error_Handling