BerriAI/litellm · error · BaseLLMException

{error_message}

Error message

{error_message}

What it means

This is not a standalone error but the base error-mapping hook: get_error_class packages a provider's HTTP error into BaseLLMException(status_code, message=error_message, headers). When you see this exception from the interactions path, the literal '{error_message}' template means the provider returned an error response and the generic mapper forwarded its message/status verbatim.

Source

Thrown at litellm/llms/base_llm/interactions/transformation.py:278

        self,
        raw_response: httpx.Response,
        logging_obj: LiteLLMLoggingObj,
    ) -> CancelInteractionResult:
        """
        Transform the cancel interaction response.
        """

    # =========================================================
    # ERROR HANDLING
    # =========================================================

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        """
        Get the appropriate exception class for an error.
        """
        from ..chat.transformation import BaseLLMException

        raise BaseLLMException(
            status_code=status_code,
            message=error_message,
            headers=headers,
        )

    def should_fake_stream(
        self,
        model: str | None,
        stream: bool | None,
        custom_llm_provider: str | None = None,
    ) -> bool:
        """
        Returns True if litellm should fake a stream for the given model.

        Override in subclasses if the provider doesn't support native streaming.
        """
        return False

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read the status_code and message on the caught BaseLLMException — they mirror the provider's response (fix the underlying auth/payload issue).
2. Retry with backoff for 429/5xx status codes.
3. Verify api_key, api_base and request payload for 4xx codes.
4. Subclass: override get_error_class to map provider errors to litellm-specific exception types for cleaner handling.

Example fix

# before
try:
    litellm.interactions(...)
except Exception as e:
    pass  # generic, loses status code

# after
from litellm.llms.base_llm.chat.transformation import BaseLLMException
try:
    litellm.interactions(...)
except BaseLLMException as e:
    if e.status_code == 429:
        time.sleep(2); litellm.interactions(...)

def is_retryable_base_llm_exception(exc: BaseException) -> bool:
    return isinstance(exc, BaseLLMException) and exc.status_code in (408, 429, 500, 502, 503, 504)

for attempt in range(3):
    try:
        return await litellm.ainteractions(...)
    except BaseLLMException as e:
        if e.status_code in (408, 429, 503) and attempt < 2:
            await asyncio.sleep(2 ** attempt)
            continue
        raise

When it happens

Trigger: Provider returns 4xx/5xx on an interactions request (invalid API key 401, rate limit 429, bad request 400); the response handler detects the error status and calls get_error_class with the provider's error body, which then surfaces as an exception the caller must catch.

Common situations: Auth failures against custom interaction endpoints; upstream 5xx; malformed request payloads the provider rejects; expired tokens on self-hosted gateways.

Related errors

• {error_message}
• {error_message}
• Failed to fetch file '{file_path}': {e}
• Failed to list files in '{directory_path}': {e}
• Mavvrik FOCUS destination: failed to update metricsMarker ({

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/c8bc45365c8b4cb7. Report an issue: GitHub.