{"record":{"id":"ced00ac421390aa2","repo":"BerriAI/litellm","slug":"apiconnectionerror-exception-provider-error","errorCode":null,"errorMessage":"APIConnectionError: {exception_provider} - {error_str}","messagePattern":"APIConnectionError: (.+?) - (.+?)","errorType":"exception","errorClass":"APIConnectionError","httpStatus":500,"severity":"error","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":2155,"sourceCode":"            raise Timeout(\n                message=f\"Timeout Error: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                litellm_debug_info=extra_information,\n                exception_status_code=original_exception.status_code,\n            )\n        else:\n            raise APIError(\n                status_code=original_exception.status_code,\n                message=f\"APIError: {exception_provider} - {error_str}\",\n                llm_provider=custom_llm_provider,\n                model=model,\n                request=getattr(original_exception, \"request\", None),\n                litellm_debug_info=extra_information,\n            )\n    else:\n        # if no status code then it is an APIConnectionError: https://github.com/openai/openai-python#handling-errors\n        raise APIConnectionError(\n            message=f\"APIConnectionError: {exception_provider} - {error_str}\",\n            llm_provider=custom_llm_provider,\n            model=model,\n            litellm_debug_info=extra_information,\n            request=httpx.Request(method=\"POST\", url=\"https://api.openai.com/v1/\"),\n        )\n\n\ndef exception_type(\n    model,\n    original_exception,\n    custom_llm_provider,\n    completion_kwargs={},\n    extra_kwargs={},\n):\n    \"\"\"Maps an LLM Provider Exception to OpenAI Exception Format\"\"\"\n    if any(isinstance(original_exception, exc_type) for exc_type in litellm.LITELLM_EXCEPTION_TYPES):\n        return original_exception","sourceCodeStart":2137,"sourceCodeEnd":2173,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/exception_mapping_utils.py#L2137-L2173","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typos in api_base, self-hosted endpoint (vLLM/Ollama) not started, corporate proxy interference, containers without DNS, or hitting localhost from the wrong environment.","solutions":["Verify the api_base URL is correct and reachable (curl it from the same environment).","Confirm the local inference server is actually running and listening on the expected port.","Check DNS/proxy/firewall settings; set HTTPS_PROXY if required.","Retry with backoff — transient network blips also surface here."],"exampleFix":"# before\nresp = litellm.completion(model='openai/llama3', api_base='http://locolhost:8000/v1', ...)\n\n# after\nresp = litellm.completion(model='openai/llama3', api_base='http://localhost:8000/v1', ...)","handlingStrategy":"retry","validationCode":"import socket, urllib.parse\n\ndef endpoint_reachable(api_base: str) -> bool:\n    u = urllib.parse.urlparse(api_base)\n    try:\n        socket.create_connection((u.hostname, u.port or (443 if u.scheme == 'https' else 80)), timeout=3)\n        return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":"try {\n  await litellm.completion(...);\n} catch (e) {\n  if (e instanceof litellm.APIConnectionError) { /* check api_base/DNS, then bounded retry */ }\n}","preventionTips":["Validate api_base reachability at startup (TCP/health check).","Run connection checks in the same network environment as the app (container, VPC).","Retry APIConnectionError with capped backoff for transient network faults."],"tags":["network","connection","dns","api-base"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}