Unable to connect to API (ConnectionRefused) in Claude: causes and fixes

The message "Unable to connect to API (ConnectionRefused)" in Claude Code means the program could not even open a connection to the address it was given. This is not a key error (that would be a 401) and not a balance error (402): the request simply never reached a server. Below are the causes from most to least common and a curl-based diagnostic order that shows in five minutes where the break is.

What ConnectionRefused means

"Connection refused" is a rejection at the connection level: nothing accepts connections at that address and port, or a proxy between you and the server refuses them. If a server had received the request and rejected it, you would see an HTTP code with a response body. So the first rule of diagnosis is to find out whether you get any HTTP response at all. If you do, the network works and the problem is the key, the model or the balance. If you do not, look at the address, proxy, DNS or network.

Causes by frequency

1. Wrong ANTHROPIC_BASE_URL. A typo in the domain, http:// instead of https://, a stray port, the address of a local proxy that was once set up and is no longer running (for example http://localhost:3456).
2. The variable does not reach Claude Code. You wrote it into ~/.zshrc but launch the editor or terminal from a graphical shell that does not read it. Or the variable is set in a different terminal window.
3. A dead or wrong proxy. HTTPS_PROXY or HTTP_PROXY is set to an address where nothing listens.
4. DNS does not resolve the domain. A resolver problem, a corporate DNS issue, or the hosts file.
5. The network cuts outbound connections. A corporate firewall or organization network limits. A network administrator helps here.
6. The address with or without /v1. For Claude Code this usually gives a 404, not a refusal, but extra path segments in the address are worth removing too.

Diagnostics in five minutes

Step 1. What is actually set

In the same terminal where you run claude:

echo "$ANTHROPIC_BASE_URL"
echo "${ANTHROPIC_AUTH_TOKEN:0:9}"   # first characters of the key, should be fetch_...
env | grep -i proxy

For Zukko the right values are ANTHROPIC_BASE_URL=https://api.zukko.pro (without /v1, with https) and ANTHROPIC_AUTH_TOKEN=fetch_.... Empty output means the variable is not set in this session. In PowerShell use $env:ANTHROPIC_BASE_URL and Get-ChildItem Env:*proxy*. If you set variables in the Claude Code settings file (an env block in settings.json), check the Claude Code documentation↗ and look at that file too: it can override environment variables. Inside a session you can also try the /status command, if your version has it.

Step 2. Is the server reachable

curl -sS -o /dev/null -w "%{http_code}\n" https://api.zukko.pro/v1/models

The model list is public and does not check the key, so this command only answers the network question. We check the key in step 3. In PowerShell call curl.exe, because curl there is an alias for another command. Read the result:

Step 3. Check the key and the messages format

If GET /v1/models answers, test the same path Claude Code uses. This request does check the key:

curl -sS https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'

A response with model text means the key and the API work and the error lies in the Claude Code environment. 401 means a wrong key, 402 not enough balance, model_not_found a wrong model name (the list of available ones comes from GET /v1/models). Other codes are described in the authentication docs↗.

Fixes by cause

Wrong address. Change it to https://api.zukko.pro, without /v1 and without a trailing path. If you doubt where /v1 is needed and where not, read the article Base URL with or without /v1↗.

A local proxy address is left over. Run unset ANTHROPIC_BASE_URL (or remove the line from ~/.zshrc, or from system variables on Windows), open a new terminal and set the correct address. Check whether the old value sits in the Claude Code settings file.

Variables are not visible. Set them in your shell profile (~/.zshrc, ~/.bashrc) and start Claude Code from a new terminal. If you launch from an editor, open it from a terminal or set the variables in its terminal settings. On Windows you need to restart the terminal after changing system variables.

A wrong proxy. If you need a proxy (for example, in an organization), fix its address. If you do not, remove HTTPS_PROXY and HTTP_PROXY for this session: unset HTTPS_PROXY HTTP_PROXY. If the network is corporate and outbound connections are restricted, ask the administrator: they know which addresses are allowed.

DNS. Check nslookup api.zukko.pro. If the domain is not found, change the system DNS server to another one available to you or check the hosts file for stale entries.

Certificates and time. TLS errors are often caused by a wrong system clock or an organization proxy substituting its own certificate. In an organization the proxy's root certificate is added to the trusted store according to your IT department's rules.

If the error persists after the fixes

1. Repeat step 2 from another network (for example a mobile hotspot): if it returns 200 there, the cause is in your main network.
2. Try the request from another computer. That separates a problem on your machine from a network problem.
3. If curl returns 503, that is already a server response, not a refused connection: the model provider is unavailable or the model is switched off (model_disabled); pick another model from GET /v1/models.
4. If Claude Code instead asks you to log in to an Anthropic account, that is a different situation: Claude Code asks to log in to Anthropic↗.

FAQ

Is "Unable to connect to API" a key problem?

No. A wrong key makes the server answer 401, while here the connection is not established at all. Still, check the key with the request from step 3: if it returns 401, the network is fine and the key needs replacing.

Does Claude Code work from Russia?

Access from Russia goes through a gateway: set https://api.zukko.pro in ANTHROPIC_BASE_URL, create a key in the dashboard, pay by SBP, MasterCard or crypto. If ConnectionRefused still appears after setup, the diagnostics above will show where the break is.

Should I add /v1 to ANTHROPIC_BASE_URL?

No. Claude Code appends /v1/messages itself, so for it the address has no /v1. Adding it by mistake usually leads to a 404.

How do I quickly check that the key and balance are fine?

Run the request from step 3: a model reply means the key is valid and the balance is sufficient (otherwise you would get 401 or 402). The remaining balance and usage are visible in the dashboard under "Usage".

The key and Claude Code settings live in the dashboard↗: create a key, set the two environment variables and repeat the check.