---
title: "Claude Code Connection Timeout and Errors: 4-Layer Checklist"
description: "Fix Claude Code connection timeouts and errors layer by layer: service status, local network, exit IP and local config. Includes a curl timing command, an error-code table and cdnping tools."
url: https://cdnping.org/en/blog/claude-code-connection-troubleshooting
language: en
published: 2026-10-17
category: "Troubleshooting"
tags: ["Claude Code","Network troubleshooting","API status","IP check","Developer tools"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Claude Code Connection Timeout and Errors: 4-Layer Checklist

When Claude Code times out or throws a connection error, the cause is usually in one of four places: a server-side outage, a broken local network, a restricted exit IP, or a misconfigured local setup. The recommended order is to check service status first, then test connectivity from your machine to `api.anthropic.com`, then look at your exit IP, and finally verify environment variables and config files. Each layer below comes with concrete checks.

## Start with the symptom: which layer does the error point to?

Before changing anything, write down the exact error text Claude Code gave you. Different errors map roughly to different layers:

| Symptom or error | Most likely layer | What to do first |
|---|---|---|
| `Connection error`, `ETIMEDOUT`, `ECONNRESET`, long hangs with no response | Local network / exit | The curl test in layer 2 |
| `ENOTFOUND`, DNS resolution failure | Local network | Check DNS and your proxy's DNS settings |
| `self signed certificate`, `unable to verify` and similar certificate errors | Local network (corporate proxy, traffic-capture tools) | Check certificates and `NODE_EXTRA_CA_CERTS` |
| HTTP 401, `authentication_error` | Config | Verify the API key or login state |
| HTTP 403, `permission_error` | Exit or account | The exit check in layer 3, plus account permissions |
| HTTP 429, `rate_limit_error` | Usage limits | Reduce concurrency and wait for the limit to reset |
| HTTP 500, 529, `overloaded_error` | Server side | Layer 1, check the status page |

This mapping is a rule of thumb, not an absolute rule. For example, a 403 can come from account permissions or from the region a request originates from, so read it together with the checks below.

## Layer 1: Is the Claude service itself down?

If the problem is on the server side, nothing you change locally will help, so this check comes first.

### How to check

1. Open cdnping's [Is Claude Code down?](/en/down/claude-code) page. It combines the official status page, an API probe every 5 minutes, and one-click user reports (can't connect, slow, rate-limited, logged out, and so on). If reports cluster within a short window and other people see the same error as you, it is very likely a server-side problem.
2. Then check [Anthropic API status](/en/status/anthropic). cdnping probes the official API entry point from Cloudflare's edge every 5 minutes, syncs the official Anthropic status page every 15 minutes, and keeps 30 days of history.
3. Treat the official status page, [status.anthropic.com](https://status.anthropic.com), as the final authority.

### Reference data

Below are cdnping's probe results against `api.anthropic.com` from Cloudflare's Denver node (DEN) during the window 2026-10-17 08:40-10:05 (UTC):

| Metric | Value |
|---|---|
| Latest latency | 77 ms |
| Median in window (p50) | 73 ms |
| p95 in window | 84 ms |
| Availability in window | 100% |

Source: cdnping /status edge probe, released as open data under CC BY 4.0. cdnping only began collecting on 2026-10-17, and this window is under an hour and a half, so it shows only that the entry point was reachable at that time. The numbers come from an edge node outside China and do not represent the latency you would measure from your own machine in mainland China.

Another data set comes from the official Anthropic status page records that cdnping syncs: over the 30 days from 2026-09-17 to 2026-10-17, 8 Claude-related incidents were recorded, of which 6 were marked major, 1 minor and 1 none by the official page. The snapshot's most recent 40 incidents (2026-10-09 to 10-16) contain no Claude entries. Eight incidents in a month is not a small number, so spending half a minute on the status page when you hit an error is a better bet than editing local config right away.

During the same period, cdnping also recorded several incidents on Cloudflare itself, for example "Elevated Errors in China Network Colos" starting 2026-10-10 (marked minor by the official page). The /status page also syncs Cloudflare's status page. If infrastructure along your path has a problem, it can show up as connection errors too, so compare the two.

## Layer 2: Can your machine reach api.anthropic.com?

If the service is healthy, narrow the problem down to the path from your machine to `api.anthropic.com`.

### Split DNS, TCP and TLS timing with curl

```bash
curl -sS -o /dev/null \
  -w "DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\nHTTP: %{http_code}\n" \
  https://api.anthropic.com/v1/messages
```

A request without a key that returns 401, 404 or 405 is normal; it means the network already reaches the server. Interpret the output like this:

- DNS takes very long or fails outright: there is a resolution problem. Try a different resolver, or check your proxy software's DNS settings.
- TCP hangs or times out: the connection is not being established, so the problem is in routing or the exit.
- TLS fails or reports a certificate error: common with a corporate HTTPS inspection proxy, or when a traffic-capture tool is running locally.
- Everything looks fine but Claude Code still times out: most likely Claude Code is not taking the path you think it is. Jump straight to layer 4 and check the config.

### claude.ai opens in the browser, but the terminal can't connect

This usually means the browser goes through the system proxy while the terminal does not. First look at the proxy variables actually in effect in your terminal:

```bash
env | grep -i -E "https?_proxy|no_proxy|all_proxy"
```

Then open the cdnping [home page speed test](/en/) in your browser and look at the Claude row's "first connection" (including DNS and the TLS handshake) and "round trip" (the median of 3 requests after the connection is reused). If the browser test succeeds while terminal curl fails, the two are not taking the same path.

## Layer 3: Is your exit IP restricted?

If the network is reachable but requests return 403, or the connection is dropped soon after it is established, look at your exit IP.

One premise first: Anthropic only serves supported countries and regions. Go by the officially published list of supported regions, and follow the terms of service and local regulations. This article only covers how to pin down where the problem is; it does not discuss ways around region restrictions.

### What to look at on the /ip page

Open cdnping's [IP and environment check](/en/ip) and focus on these items:

| Check | What to look at | Notes |
|---|---|---|
| Exit IP intelligence | Location, IP type, native or broadcast | 11 geolocation databases vote and give a confidence level; types are datacenter, residential, mobile and Tor |
| Reputation | Which reputation sources flagged it | Aggregates 14 reputation sources, with the weight of each hit published |
| Multi-exit detection | The exit that Claude and other sites see | Reads the Cloudflare trace from Claude, ChatGPT and Grok to see whether different sites are reached through different exits |
| Mainland China split-routing detection | Split / global / direct | Judged from the client IP and latency reported back by several Chinese CDNs |
| Latency signature | Difference between browser round trip and exit TCP round trip | A clearly large difference means there is another relay layer in between |
| DNS leak | Where resolution requests originate | When resolution and connection take different paths, you may get an unsuitable resolution result |

For troubleshooting Claude Code, multi-exit detection and split-routing detection are the most useful. A common situation is that you assume all traffic goes through one exit, but Claude's requests actually follow a routing rule onto a different line, or go out over your local network directly. Comparing the two results confirms where Claude's requests really leave from. For how split routing works, see [What is split tunneling](/en/learn/split-tunneling); for the difference between native and broadcast IPs, see [this explainer](/en/learn/native-ip-vs-broadcast-ip); for how leak detection works, see [DNS leaks and WebRTC leaks](/en/learn/dns-leak-webrtc-leak).

### Generate a result image with the IP hidden when asking for help

When asking for help in a team chat or community, you can generate a single result image on the /ip page instead of taking several screenshots. The image carries a cdnping watermark, and at generation time you can choose to hide the IP address. Others can see the exit type, split-routing verdict and latency signature they need for troubleshooting, but your actual IP is not exposed. Browser fingerprint checks are computed locally and are not uploaded.

## Layer 4: Is the Claude Code config wrong?

If the first three layers are fine, the problem is in local config. Claude Code reads environment variables as well as the `env` field in `~/.claude/settings.json`, so check both.

### Check commands

```bash
# 1. Let Claude Code self-check the installation and config
claude doctor

# 2. Inspect the relevant environment variables
env | grep -E "ANTHROPIC_|API_TIMEOUT_MS|NODE_EXTRA_CA_CERTS"

# 3. View the env field in your user-level config
cat ~/.claude/settings.json

# 4. Project-level config can also override global settings
cat .claude/settings.json .claude/settings.local.json 2>/dev/null
```

Check each item:

- `ANTHROPIC_BASE_URL`: if you set a custom endpoint, check the spelling, the scheme (https) and whether there is an extra path at the end. A wrong address often produces a 404 or a connection timeout. Forgetting to remove a third-party address after you are done with it is also a frequent cause of errors.
- `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`: check whether the key has expired or has stray spaces. If several auth methods are set at once, confirm which one is actually in effect. Typing `/status` inside Claude Code shows the current account and endpoint information.
- `HTTPS_PROXY` / `NO_PROXY`: if your corporate network requires an internal proxy, confirm the variable is in effect in the terminal where Claude Code runs, and make sure `anthropic.com` was not added to `NO_PROXY` by mistake.
- `NODE_EXTRA_CA_CERTS`: a corporate HTTPS inspection proxy replaces certificates, so you need to point this at your company's root certificate, otherwise you get the certificate errors mentioned in layer 2.
- `API_TIMEOUT_MS`: on a slow network, long tasks often time out, and you can raise the request timeout. This only eases the symptom; the problem with the link itself remains.

After changing config, open a new terminal and run `claude` again to avoid leftover environment variables.

### Troubleshooting a third-party endpoint

If you use Claude Code through a third-party gateway (changing only `ANTHROPIC_BASE_URL` and the key), treat the gateway as its own layer: first confirm the gateway's own status, then look at the gateway-to-upstream leg.

Take AGI Plan as an example (AGI Plan is a commercial partner of cdnping). cdnping's [/status/agiplan](/en/status/agiplan) mirrors its public hourly request statistics; availability is computed from real requests, and only 5xx responses count as platform failures. In the same probe window as above, cdnping's probe of `agiplan.dev` from the DEN node took 883 ms. AGI Plan states clearly that it is not an officially authorized channel. Whichever way you connect, read the provider's statements about authorized channels and terms of use first.

## A checklist you can follow

| Step | Check | Tool | Pass criterion |
|---|---|---|---|
| 1 | Service status | [/down/claude-code](/en/down/claude-code), [/status/anthropic](/en/status/anthropic) | No ongoing incident, no cluster of reports |
| 2 | DNS / TCP / TLS | The curl command above | Any HTTP status code comes back |
| 3 | Terminal proxy variables | `env \| grep -i proxy` | Matches your intended network setup |
| 4 | Exit and split routing | [/ip](/en/ip) | Claude's exit is as expected, no leaks |
| 5 | Claude Code config | `claude doctor`, `/status` | Address, key and certificates are all correct |

## What to prepare ahead of time

- Bookmark [/down/claude-code](/en/down/claude-code) and check it first when an error appears.
- While your network is healthy, run a full check on [/ip](/en/ip) and save a result image with the IP hidden as a baseline, so you can compare differences next time something breaks.
- For cdnping's probe nodes, frequency and statistical methods, see [Methodology](/en/methodology); weekly stability summaries are in the [weekly reports](/en/reports).