BerriAI/litellm · error · APIConnectionError

APIConnectionError

Error message

APIConnectionError: {exception_provider} - {error_str}

What it means

When the OpenRouter exception has no status_code attribute, _map_openrouter_exception raises litellm.APIConnectionError ('APIConnectionError: <provider> - <error_str>') with a stubbed request object (POST https://api.openai.com/v1/). Following the openai-python convention cited in the code, absence of a status means the failure happened before an HTTP response existed — DNS, TCP, TLS, proxy, or client timeout.

Solutions

  1. Test reachability: curl https://openrouter.ai/api/v1/models from the same environment.
  2. Fix proxy env (HTTP_PROXY/HTTPS_PROXY/NO_PROXY) or ask for openrouter.ai on the allowlist.
  3. Raise the client timeout passed to litellm.completion(timeout=...).
  4. Retry transient drops with num_retries; APIConnectionError is retryable by litellm.

Example fix

# before
litellm.completion(model="openrouter/openai/gpt-4o", messages=msgs, timeout=5)

# after
litellm.completion(
    model="openrouter/openai/gpt-4o",
    messages=msgs,
    timeout=60,
    num_retries=3,
)
Defensive patterns

Strategy: retry

Validate before calling

import socket
from urllib.parse import urlparse
host = urlparse("https://openrouter.ai").hostname
assert socket.gethostbyname(host), "DNS for openrouter.ai failed — fix before calling"

Try / catch

try:
    resp = litellm.completion(model="openrouter/...", **kwargs)
except litellm.APIConnectionError as e:
    log.warning("transport failure to openrouter: %s", e)
    resp = litellm.completion(num_retries=3, **kwargs)

Prevention

When it happens

Trigger: Requests to https://openrouter.ai/api/v1 that never complete: DNS failure, connection refused/reset, TLS interception, egress firewall blocking the domain, httpx transport errors, or local timeout= smaller than connection latency.

Common situations: Corporate proxies/firewalls whitelisting only api.openai.com; container DNS flakiness; HTTPS_PROXY env misconfig; slow mobile/high-latency networks; OpenRouter edge unreachable from the region.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/ced00ac421390aa2. Report an issue: GitHub.

Appendix: source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:2155

            raise Timeout(
                message=f"Timeout Error: {exception_provider} - {error_str}",
                model=model,
                llm_provider=custom_llm_provider,
                litellm_debug_info=extra_information,
                exception_status_code=original_exception.status_code,
            )
        else:
            raise APIError(
                status_code=original_exception.status_code,
                message=f"APIError: {exception_provider} - {error_str}",
                llm_provider=custom_llm_provider,
                model=model,
                request=getattr(original_exception, "request", None),
                litellm_debug_info=extra_information,
            )
    else:
        # if no status code then it is an APIConnectionError: https://github.com/openai/openai-python#handling-errors
        raise APIConnectionError(
            message=f"APIConnectionError: {exception_provider} - {error_str}",
            llm_provider=custom_llm_provider,
            model=model,
            litellm_debug_info=extra_information,
            request=httpx.Request(method="POST", url="https://api.openai.com/v1/"),
        )


def exception_type(
    model,
    original_exception,
    custom_llm_provider,
    completion_kwargs={},
    extra_kwargs={},
):
    """Maps an LLM Provider Exception to OpenAI Exception Format"""
    if any(isinstance(original_exception, exc_type) for exc_type in litellm.LITELLM_EXCEPTION_TYPES):
        return original_exception

View on GitHub (pinned to 77b7c6c40c)