Learn AI Create the Future — with Pranay
Main site

Error database

APIConnectionError: Connection error (OpenAI / Anthropic)

The request never reached the provider — network, proxy, SSL interception, or a wrong base_url. Test with curl to split the problem in half.

The message you saw
APIConnectionError: Connection error (OpenAI / Anthropic)

By Updated

The error

Output
openai.APIConnectionError: Connection error.

Underneath it, the traceback usually carries the real clue from httpx:

Output
httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
httpx.ConnectTimeout: timed out
httpx.ConnectError: [Errno -3] Temporary failure in name resolution

What it means

The HTTP request failed below the API level — no status code, no server response, nothing reached the provider. The API is not rejecting you; the network path is broken. The httpx line above the SDK error names which layer: DNS, TCP, TLS or timeout. Read that line first; it halves the search.

Why it happens

In rough order of frequency: no or flaky internet; a corporate proxy that must be traversed (and often inspects TLS, breaking certificate verification); a firewall or country-level block on the API domain; a VPN detour; a wrong or stale base_url pointing at a dead gateway or local server; DNS failure inside Docker containers; and occasionally IPv6 misbehaviour on networks that advertise it but route it badly.

How to fix it

1. Split the problem with curl.

bash
curl -sS https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" -o /dev/null -w "%{http_code}\n"

Any HTTP status (even 401) means the network path works and the problem is in your Python environment's networking. A curl failure means the machine or network itself, and Python is innocent.

2. On corporate networks, set the proxy — and the CA bundle.

bash
export HTTPS_PROXY=http://proxy.company.com:8080
export SSL_CERT_FILE=/path/to/company-root-ca.pem
export REQUESTS_CA_BUNDLE=/path/to/company-root-ca.pem

TLS-inspecting proxies re-sign traffic with the company's certificate; Python must be told to trust it. Get the .pem from your IT team. The dedicated SSL page covers the variants.

3. Check base_url if one is set anywhere. Environment variables like OPENAI_BASE_URL, gateway configs and local-LLM settings survive long after the server they pointed to. Unset it to talk to the real API:

bash
env | grep -i base_url

4. In Docker, verify DNS from inside the container.

bash
docker exec -it mycontainer python -c "import socket; print(socket.gethostbyname('api.openai.com'))"

Name-resolution failures inside containers are fixed at the Docker daemon or compose level (dns: setting), not in your app.

5. For slow networks, extend the timeout instead of retrying blind.

python
from openai import OpenAI
client = OpenAI(timeout=60.0)      # seconds

How to prevent it

Wrap API calls with the same backoff-and-retry used for 529s — transient network blips then self-heal. Keep proxy and CA settings in the project's documented environment setup so new machines start life configured. And log the underlying httpx exception class, not only the SDK wrapper, so future incidents diagnose themselves.