Claude Code "Unable to connect to API": each code and its fix
ECONNREFUSED, ENOTFOUND, EHOSTUNREACH, ERR_PROXY_TUNNEL, ECONNRESET and certificate errors in Claude Code: the cause and the command that confirms it.
“Unable to connect to API” means the request never reached Anthropic, and the code in brackets says where it stopped. ConnectionRefused is often a leftover ANTHROPIC_BASE_URL or a proxy that isn’t running. ENOTFOUND is DNS. EHOSTUNREACH is routing, typically a VPN or an exit node. ERR_PROXY_TUNNEL is a proxy refusing the tunnel. ECONNRESET is a connection cut partway. A certificate error is a TLS-inspecting proxy, fixed with NODE_EXTRA_CA_CERTS. Start with curl -I https://api.anthropic.com from the same shell: any HTTP status back means the network is fine and the problem is Claude Code’s own settings.
The messages
The general line has variants that name the cause. Anthropic’s error reference lists the family:
Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settingsCopiedBefore showing any of these, Claude Code retries dropped connections, timeouts and server errors “up to 10 times with exponential backoff,” so by the time you read one, the failure has repeated. In a script, lowering CLAUDE_CODE_MAX_RETRIES makes it fail sooner. The banner Waiting for API response · will retry in … is not an error yet: it means 20 seconds have passed with no data.
The first check
curl -I https://api.anthropic.com
echo "$ANTHROPIC_BASE_URL"
env | grep -io '^[a-z_]*proxy=' # which proxy variables are set, not their valuesCopiedcurl honours the standard proxy variables too, so it tests much the same route out, but it ignores ANTHROPIC_BASE_URL. If curl gets a status line back and Claude Code still fails, look at that variable first.
Each code, its cause on a server, and the check
Connection refused (ConnectionRefused, ECONNREFUSED)
Something answered and refused the connection. The most common cause, in Anthropic’s words, is ANTHROPIC_BASE_URL left pointing at “a local proxy or gateway that’s no longer running,” which “produces Connection refused even though curl reaches the API.” On a server that tried a gateway or a local model once, the export often outlives the experiment. The variable can also come from the env block of a settings file:
echo "$ANTHROPIC_BASE_URL"
grep -rn ANTHROPIC_BASE_URL ~/.bashrc ~/.profile ~/.claude/settings.json .claude/ 2>/dev/nullCopiedRemove it from wherever it is set and start Claude Code from a new terminal, since variables are read once at startup. If the base URL is clean, check the proxy: an HTTPS_PROXY naming a port where nothing listens refuses too. An egress firewall rule that rejects outbound traffic, rather than silently dropping it, is the third case. A rule that drops usually shows up as Request timed out instead.
Can’t reach the API server (ENOTFOUND)
The name api.anthropic.com did not resolve.
getent hosts api.anthropic.com # no output means no answer
cat /etc/resolv.conf
resolvectl status # on systemd-resolved, e.g. UbuntuCopiedAnthropic points Linux users at /etc/resolv.conf for an unreachable nameserver. On a server, look for a resolver a VPN client wrote and left behind after it stopped. If getent finds nothing for Anthropic but getent hosts github.com answers, the resolver works and something in it is filtering Anthropic’s names.
No internet route (EHOSTUNREACH)
The kernel has no route to the address. On a cloud server whose own network works, the usual cause is something that took over the default route: a VPN client, a kill switch, or a Tailscale exit node that has gone offline, which leaves the server with no way out at all.
ip route get 1.1.1.1 # which interface the internet goes out on
sudo tailscale set --exit-node= # stop using an exit node, then retryCopiedIf ip route get names tailscale0 or a VPN interface, clearing that setting and retrying is the test. A VPN with a kill switch can block traffic even when disconnected; the NordVPN and Tailscale guide covers that on Linux.
Couldn’t connect through your proxy (ERR_PROXY_TUNNEL)
The proxy was reached and refused to open a tunnel to Anthropic. The message gives the two causes: the proxy’s credentials, or a rule that doesn’t allow the host. The verbose curl shows the proxy’s reply, typically a 407 for missing credentials or a 403 for a blocked host:
curl -sv https://api.anthropic.com -o /dev/null 2>&1 | grep -i -e proxy -e CONNECT -e "HTTP/"CopiedCredentials go in the proxy URL, http://user:password@proxy.example.com:8080. Claude Code reads https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY in that order and uses the first one set, so a stale lowercase variable beats a correct uppercase one. It does not support SOCKS proxies, so an SSH -D tunnel cannot be its proxy. A URL it cannot parse, such as one missing http://, stops it at launch with an error naming the variable.
Connection dropped (ECONNRESET)
The connection opened and was cut. Occasional resets are retried and you never see them. Two patterns get as far as the message:
- Every request drops, through a gateway. With
ANTHROPIC_BASE_URLset, Anthropic’s first suspect is a gateway or upstream that rejects the tool search fields Claude Code sends by default. - Resets on one network path. A long-running report from users on several home ISPs, open as of November 2026, finds resets on the direct path to Anthropic that disappear through a VPN or with the network interface’s MTU lowered to 1400. The cause is still argued in the thread. On a server, a firewall or proxy that ends idle or long connections can produce the same symptom.
To tell them apart, run the same prompt from another network or through the VPN. If it works there, the reset happens on the path, not in Claude Code.
Request timed out
No answer at all, usually a firewall that drops outbound packets or a proxy that is needed but not set. curl -I --max-time 10 https://api.anthropic.com hanging to its limit confirms it. A server behind an egress allowlist needs at least api.anthropic.com, and claude.ai, claude.com and platform.claude.com to sign in with a plan, as Anthropic’s host list says. The native updater also needs downloads.claude.ai.
The certificate errors
These come from a proxy or security appliance that intercepts TLS with its own certificate:
Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). …
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). …CopiedAt sign-in and in the startup check, the same failure reads SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). These are not retried, so they appear on the first attempt. To see who signed the certificate your server receives:
curl -sv https://api.anthropic.com -o /dev/null 2>&1 | grep -i issuerCopiedAn issuer named after your company or a security product, rather than a public certificate authority, is the interception. The fix is to trust that authority’s certificate, either by adding it to the system store or by pointing Claude Code at it:
# system store (Ubuntu, Debian)
sudo cp corp-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# or for Claude Code only
export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pemCopiedClaude Code reads the system store when installed with the native installer, and on npm installs only with Node 22.15 or later. Older Node sees only its bundled set and NODE_EXTRA_CA_CERTS. To confirm the file loaded, start claude --debug and look in ~/.claude/debug/ for CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS. Anthropic says plainly not to set NODE_TLS_REJECT_UNAUTHORIZED=0, which switches certificate checking off for everything. On a fresh minimal image the same error can mean no certificate authorities at all; the Linux install guide has that fix.
When it works by hand and fails in a job
A proxy, a CA path or a base URL exported in your interactive shell does not reach a systemd timer or a cron job, which start with their own environment. Background agents are hosted by a supervisor process that keeps the environment of whichever shell started it first. Anthropic’s advice for background agents is to put network variables in the env block of ~/.claude/settings.json instead, and that user settings file is read by a timer job running as the same user too. The other parts of an unattended setup are in running Claude Code headless on a schedule.
If the message is “Unable to connect to Anthropic services” at first run, the same checks apply: it tests api.anthropic.com and platform.claude.com, and names a proxy variable when one is set. If every network check passes and it still fails, Claude Code may not be offered in the server’s country.