Fix: APIConnectionError "Connection error." (OpenAI, Anthropic)

“Connection error.” means the SDK never got an answer from the API at all: no status code, no error body. It says nothing about your API key, your model or your code. The SDK’s message is the same for every cause, and both OpenAI’s and Anthropic’s SDKs use the same class and wording. The real reason is two levels down, in the error’s cause.

Read the cause first

try {
  await client.chat.completions.create({ /* … */ });
} catch (err) {
  console.error(err.cause?.cause ?? err.cause);
}

If the message is Request timed out. instead (APIConnectionTimeoutError), the connection was made but the answer took longer than the SDK’s timeout. That’s a different problem: raise timeout, or ask for less.

1. ECONNREFUSED: a local model server that isn’t running

The most common one now. You point baseURL at Ollama, LM Studio or a local proxy, and it isn’t started:

APIConnectionError: Connection error.
  cause → TypeError: fetch failed
  cause → AggregateError: ECONNREFUSED

That was baseURL: 'http://localhost:11434/v1' (Ollama’s port) with nothing running. Anthropic’s SDK with the same address failed identically.

curl http://localhost:11434/v1/models

2. ENOTFOUND: a typo or a wrong base URL

APIConnectionError: Connection error.
  cause → TypeError: fetch failed
  cause → Error: getaddrinfo ENOTFOUND api.openai.con

One letter off in baseURL (or in an environment variable like OPENAI_BASE_URL) and the name simply doesn’t exist. The cause prints the exact host it tried, so compare it character by character.

3. Something is replacing the HTTPS certificate

This is the confusing one, because it only happens on some machines. Company SSL inspection and antivirus “HTTPS scanning” both work the same way: they decrypt your traffic and re-sign it with their own certificate. Node doesn’t trust that certificate by default, so the connection fails:

APIConnectionError: Connection error.
  cause → TypeError: fetch failed
  cause → Error: unable to verify the first certificate; if the root CA is installed locally,
          try running Node.js with --use-system-ca
  code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'

I hit this for real. The test machine runs Avast, whose Web Shield intercepts HTTPS: the certificate Node received for api.openai.com was issued by Avast Web/Mail Shield Root, not by OpenAI’s CA. With nothing telling Node to trust that root, both SDKs failed against the real APIs with the message above.

node --use-system-ca app.js

NODE_USE_SYSTEM_CA=1

4. A proxy you set, which Node ignores

On networks where everything must go through a proxy, people set HTTPS_PROXY and expect it to be used. The SDKs call Node’s built-in fetch, and by default it ignores that variable.

I ran a local proxy that logs every connection, set HTTPS_PROXY=http://127.0.0.1:8899, and called the API. The request succeeded, and the proxy log stayed empty: it went straight out, past the proxy. I couldn’t block direct traffic on this machine to show the failure itself, but on a network that only lets traffic out through the proxy, that direct attempt is the one that can’t get through.

NODE_USE_ENV_PROXY=1

What didn’t work

How this was tested

The OpenAI JavaScript SDK 7.30.0 and Anthropic’s 0.131.0 on Node 24.14.0, Windows 11, each making one chat request with a fake key, so the only possible success was a 401 from the real API. Causes were produced on purpose: a baseURL on a closed port, a misspelled host, a request timeout of 1 ms, a local logging proxy, and the machine’s own Avast HTTPS scanning, with Node’s certificate settings added and removed one at a time. I tested the JavaScript SDKs only. Python’s SDKs use the same error class name but a different HTTP client, so their proxy and certificate behaviour may differ.