BerriAI/litellm · error · APIConnectionError

APIConnectionError: {exception_provider} - {error_str}

Error message

APIConnectionError: {exception_provider} - {error_str}

What it means

When the original exception has NO status_code, litellm treats it as a connection-level failure (following openai-python's convention) and raises APIConnectionError. This means the HTTP request likely never completed — DNS failure, refused connection, TLS error, or a network interruption.

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 6c2dcb801b)

Solutions

1. Verify the api_base URL is correct and reachable (curl it from the same environment).
2. Confirm the local inference server is actually running and listening on the expected port.
3. Check DNS/proxy/firewall settings; set HTTPS_PROXY if required.
4. Retry with backoff — transient network blips also surface here.

Example fix

# before
resp = litellm.completion(model='openai/llama3', api_base='http://locolhost:8000/v1', ...)

# after
resp = litellm.completion(model='openai/llama3', api_base='http://localhost:8000/v1', ...)

import socket, urllib.parse

def endpoint_reachable(api_base: str) -> bool:
    u = urllib.parse.urlparse(api_base)
    try:
        socket.create_connection((u.hostname, u.port or (443 if u.scheme == 'https' else 80)), timeout=3)
        return True
    except OSError:
        return False

try {
  await litellm.completion(...);
} catch (e) {
  if (e instanceof litellm.APIConnectionError) { /* check api_base/DNS, then bounded retry */ }
}

When it happens

Trigger: completion() calls where the underlying httpx/openai call fails before any response: wrong api_base hostname, provider endpoint down, local proxy not listening, firewall/DNS blocking, or missing internet access.

Common situations: Typos in api_base, self-hosted endpoint (vLLM/Ollama) not started, corporate proxy interference, containers without DNS, or hitting localhost from the wrong environment.

Related errors

• Error listing files in '{directory_path}': {e}
• DNS resolution failed for '{hostname}': {e}
• Invalid content moderation response: {redacted_text}
• Error from qdrant checking if /collections exist {collection
• Redis circuit breaker is open — skipping {name}

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