{"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/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/litellm_core_utils/exception_mapping_utils.py#L2137-L2173","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Test reachability: curl https://openrouter.ai/api/v1/models from the same environment.","Fix proxy env (HTTP_PROXY/HTTPS_PROXY/NO_PROXY) or ask for openrouter.ai on the allowlist.","Raise the client timeout passed to litellm.completion(timeout=...).","Retry transient drops with num_retries; APIConnectionError is retryable by litellm."],"exampleFix":"# before\nlitellm.completion(model=\"openrouter/openai/gpt-4o\", messages=msgs, timeout=5)\n\n# after\nlitellm.completion(\n    model=\"openrouter/openai/gpt-4o\",\n    messages=msgs,\n    timeout=60,\n    num_retries=3,\n)","handlingStrategy":"retry","validationCode":"import socket\nfrom urllib.parse import urlparse\nhost = urlparse(\"https://openrouter.ai\").hostname\nassert socket.gethostbyname(host), \"DNS for openrouter.ai failed — fix before calling\"","typeGuard":null,"tryCatchPattern":"try:\n    resp = litellm.completion(model=\"openrouter/...\", **kwargs)\nexcept litellm.APIConnectionError as e:\n    log.warning(\"transport failure to openrouter: %s\", e)\n    resp = litellm.completion(num_retries=3, **kwargs)","preventionTips":["Allowlist openrouter.ai in corporate proxies/firewalls.","Set an explicit timeout ≥ 60s; defaults can be too tight on slow networks.","Use num_retries so transport blips are absorbed automatically."],"tags":["openrouter","connection-error","network","no-status-code","litellm","exception-mapping"],"backgroundTag":"api-connection-failed","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}