Fix Claude Code "API Error: Connection error" (Unable to connect to API)

Other forms of the same error

• API Error (Connection error.) · Retrying in 1 seconds… (attempt 1/10)
• Couldn't connect through your proxy (ECONNREFUSED)
• TypeError (fetch failed)
• Unable to connect to Anthropic services · Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

What this error tells you

Connection error, fetch failed and Unable to connect to API (...) are fundamentally different from a 401, 429 or 503. Those are HTTP errors that CCSub sent back, so the request arrived. Connection errors mean no connection was ever established, and CCSub has no record of the attempt. The problem lives on your machine: network, proxy, firewall, or DNS.

Recent Claude Code versions put the underlying error code in parentheses. Older ones print API Error (Connection error.) together with TypeError (fetch failed) and retry up to 10 times. What the codes mean:

• ECONNREFUSED — the target refused the connection. Most often a proxy variable is pointing at a local proxy port with nothing listening.
• ENOTFOUND — the hostname didn't resolve. Check ANTHROPIC_BASE_URL for typos; it should be https://www.ccsub.net.
• ETIMEDOUT — the connection attempt timed out. The network is down, or a proxy or firewall is blocking the route.
• Couldn't connect through your proxy — Claude Code failed while connecting to the proxy itself. Go straight to your proxy settings.

The usual cause: a leftover proxy variable

Plenty of developers have export https_proxy=http://127.0.0.1:7890 in ~/.zshrc, or pasted a "copy terminal proxy command" snippet from a proxy app at some point. Later they quit the proxy app, but every new terminal still carries the variable. Claude Code dutifully sends each request to port 7890 and gets ECONNREFUSED.

Claude Code honors the standard proxy variables in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY, and it doesn't support SOCKS. To track it down:

# 1. See which proxy variables this shell has
env | grep -i proxy

# 2. Remove them for this shell only
unset https_proxy HTTPS_PROXY http_proxy HTTP_PROXY all_proxy ALL_PROXY

# 3. Or keep the proxy and send CCSub direct
export NO_PROXY="www.ccsub.net,ccsub.net"

To make it permanent, delete those export lines from your shell profile or add the NO_PROXY line. Also check the env block in ~/.claude/settings.json for a hard-coded proxy; the /status screen in Claude Code shows the proxy currently in effect.

Proxy apps in TUN or global mode can capture traffic even without environment variables. Add a direct rule for ccsub.net (in Clash-style configs: DOMAIN-SUFFIX,ccsub.net,DIRECT), or switch global mode off while you work. CCSub is reachable directly and doesn't need to go through a proxy.

Use curl to rule the network in or out

Run this in the same terminal you start Claude Code from:

curl -sS -X POST https://www.ccsub.net/v1/messages -o /dev/null -w '%{http_code}\n'

curl reads the same proxy variables, so it sees the same network Claude Code does. 401 means you reached CCSub (no key was sent, hence 401) — the network is fine and the issue is your Claude Code config. A hang, Could not resolve host or Connection refused means it's your network or proxy.

"Unable to connect to Anthropic services" on first launch

The first time you run claude, the onboarding flow checks that it can reach api.anthropic.com. That check doesn't use your ANTHROPIC_BASE_URL, so on networks where Anthropic's API is blocked or unreachable it fails with Unable to connect to Anthropic services. There's an open report about this on the Claude Code issue tracker; the common workaround is to skip onboarding. Open ~/.claude.json — the file in your home directory, not the ~/.claude/ folder — and add this to the top-level JSON object:

"hasCompletedOnboarding": true

Save and run claude again. If the file doesn't exist, create it with {"hasCompletedOnboarding": true}.

Corporate networks and certificate errors

SSL certificate verification failed or unable to get local issuer certificate usually means a corporate TLS-inspection proxy is swapping certificates. Following the official docs, set NODE_EXTRA_CA_CERTS to the path of your company's root certificate and start Claude Code again.

FAQ

Related errors

• stream disconnected before completion: stream closed before response.completedThe stream dropped before it finished. Make sure base_url is https://www.ccsub.net/api/v1, take local proxies out of the path, shorten very long turns, and raise stream_max_retries on the provider.
• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}The key never arrived or it's the wrong one. Check /status, re-copy the full key from the dashboard, and unset any leftover ANTHROPIC_API_KEY.
• API Error: 504 {"type":"error","error":{"type":"timeout_error","message":"Upstream timed out"}}The upstream took too long to start answering. Use streaming (stream: true) in your own code, /compact very long contexts, and split long outputs. A one-off 504 just needs a retry and isn't billed.