BerriAI/litellm · error · APIConnectionError

{exception_provider} APIConnectionError - {message}\n{_redac

Error message

{exception_provider} APIConnectionError - {message}\n{_redact_string(traceback.format_exc())}

What it means

When an Azure exception carries no status_code attribute, _map_azure_exception assumes the request never reached a valid HTTP response and raises litellm.APIConnectionError. The message embeds the exception_provider, the original message, and a redacted traceback, because for connection errors the SDK traceback is usually the only diagnostic (see the openai-python error-handling convention referenced in the code).

Source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:2061

            raise Timeout(
                message=f"AzureException Timeout - {message}",
                model=model,
                litellm_debug_info=extra_information,
                llm_provider="azure",
                exception_status_code=original_exception.status_code,
            )
        else:
            raise APIError(
                status_code=original_exception.status_code,
                message=f"AzureException APIError - {message}",
                llm_provider="azure",
                litellm_debug_info=extra_information,
                model=model,
                request=httpx.Request(method="POST", url="https://openai.com/"),
            )
    else:
        # if no status code then it is an APIConnectionError: https://github.com/openai/openai-python#handling-errors
        raise APIConnectionError(
            message=f"{exception_provider} APIConnectionError - {message}\n{_redact_string(traceback.format_exc())}",
            llm_provider="azure",
            model=model,
            litellm_debug_info=extra_information,
            request=httpx.Request(method="POST", url="https://openai.com/"),
        )


def _map_openrouter_exception(
    *,
    model: str,
    original_exception: _ProviderHTTPException,
    custom_llm_provider: str,
    error_str: str,
    exception_type: str,
    exception_provider: str,
    extra_information: str,
) -> None:

View on GitHub (pinned to 77b7c6c40c)

Solutions

Read the embedded traceback in the message — it names the underlying network error (DNS, TLS, proxy, refused).
Verify connectivity: curl your api_base endpoint (e.g. https://<resource>.openai.azure.com) from the same host/container.
Fix environment config: AZURE_API_BASE, AZURE_API_KEY / azure_ad_token, and any HTTPS_PROXY/HTTP_PROXY settings.
For transient drops, configure retries: litellm.completion(..., num_retries=3) which retries APIConnectionError.

Example fix

# before
litellm.completion(model="azure/dep", messages=msgs)

# after
import litellm
try:
    litellm.completion(model="azure/dep", messages=msgs)
except litellm.APIConnectionError as e:
    # message contains original exception + redacted traceback
    log.error("network failure talking to Azure: %s", e)
    raise

Defensive patterns

Strategy: retry

Validate before calling

# pre-flight: can we reach the Azure endpoint at all?
import socket, ssl
from urllib.parse import urlparse
host = urlparse(os.environ["AZURE_API_BASE"]).hostname
try:
    socket.create_connection((host, 443), timeout=5).close()
    print("reachable")
except OSError as e:
    print("network issue before calling litellm:", e)

Try / catch

try:
    resp = litellm.completion(**kwargs)
except litellm.APIConnectionError as e:
    if "Azure" in str(e) or kwargs.get("model", "").startswith("azure/"):
        log.warning("azure network failure (traceback in message): %s", e)
        resp = litellm.completion(num_retries=3, **kwargs)  # or fix DNS/proxy then retry
    else:
        raise

Prevention

Smoke-test AZURE_API_BASE reachability from every deploy environment at startup.
Keep HTTPS_PROXY/NO_PROXY correct in containers; missing proxy config is the top cause.
Set num_retries so transient connection errors are retried automatically.
Treat the embedded traceback as the diagnostic, not the exception class name.

When it happens

Trigger: Network-level failures before/while talking to Azure: DNS resolution failure, connection refused, TLS certificate errors, proxy misconfiguration, httpx.ConnectError/ReadError, or an api_base pointing at an unreachable host.

Common situations: Wrong or malformed azure_ad_token / api_base in env vars; corporate egress proxies blocking *.openai.azure.com; containers with no DNS; self-signed TLS interception; transient network drops in CI runners.

Related errors

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