How to Diagnose and Fix Claude Code Network and Connection Errors in 5 Minutes

When Claude Code suddenly throws a "connection failed" or "request timed out" error, it's tempting to immediately reinstall or blame your setup. But the same symptom — "it's not working" — can have completely different causes: a network outage, an expired API key, or an overloaded Anthropic server. Fixing the wrong thing just wastes time.

This guide helps you systematically identify the actual cause of network and connection errors in Claude Code, with a diagnosis flow you can complete in about 5 minutes.

Common Error Messages and What They Mean

Before diving into troubleshooting steps, it helps to know which layer is actually failing. Here's a quick reference:

API connectivity errors:

• Failed to connect to api.anthropic.com — DNS resolution failure or firewall blocking outbound connections
• ECONNREFUSED — A local proxy misconfiguration or port conflict
• ECONNRESET — The connection was dropped mid-request (unstable network or server-side timeout)
• ETIMEDOUT — Network is too slow, or the request took longer than the allowed timeout

Authentication errors (not network issues):

• 401 Unauthorized — Your API key is invalid or expired
• 403 Forbidden — The API key doesn't have permission for this model or feature

Server-side issues (nothing you can fix):

• 529 Overloaded — Anthropic's servers are under high load
• 500 Internal Server Error — A temporary server-side failure

The key insight: 401 and 529 errors mean your network connection is actually working fine — they're different problems that just look similar to "can't connect."

A 5-Minute Diagnosis Flow

Going through these steps in order will identify the root cause in the vast majority of cases.

Step 1: Check Anthropic's status page first

Before you start poking at your own setup, rule out whether Anthropic's services are down.

# Quick check from the terminal
curl -s -o /dev/null -w "%{http_code}" https://status.anthropic.com
# 200 means the status page is up — open it in a browser to read the details

If there's a Degraded or Major Outage status, the fix is to wait. Skipping this step and spending 30 minutes debugging your environment when it's actually a service outage is a common frustration — avoid it.

Step 2: Hit the API endpoint directly with curl

Bypass Claude Code entirely and test the API connection directly.

# Make sure your API key is in the environment variable
curl -v https://api.anthropic.com/v1/models \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01"
# Expected output when working: HTTP/2 200 ... {"data": [...]}

What the results tell you:

• HTTP 200 — The API is reachable and your key is valid. The issue is in Claude Code's configuration, not the network.
• HTTP 401 — Your API key is wrong or expired.
• Could not resolve host — DNS failure or no network connection.
• Hangs with no response — Firewall is blocking outbound HTTPS to api.anthropic.com.

This single command tells you whether the problem is upstream (Anthropic/network) or in your local setup.

Step 3: Verify your API key

Authentication failures can look like network errors if you're not looking closely.

# Check if the key is set
echo $ANTHROPIC_API_KEY
 
# If empty, set it
export ANTHROPIC_API_KEY="sk-ant-YOUR_KEY_HERE"
 
# Check Claude Code's stored config
cat ~/.claude.json 2>/dev/null || echo "No config file found"

A valid API key starts with sk-ant-. If yours doesn't, or if the value is empty, generate a new key from the Anthropic Console and set it.

Step 4: Check basic network connectivity

If the API curl test failed at the connection level, dig into network health.

# DNS resolution test
nslookup api.anthropic.com
# Should return an IP address like 18.244.215.xxx
 
# Test if port 443 is reachable
nc -zv api.anthropic.com 443
# Expected: Connection to api.anthropic.com port 443 [tcp/https] succeeded!
 
# Or with curl
curl -v --connect-timeout 10 https://api.anthropic.com 2>&1 | head -20

If port 443 is unreachable, the issue is a firewall rule or routing problem — not Claude Code itself.

Fixing Specific Error Types

DNS resolution failures

If nslookup or dig can't resolve api.anthropic.com, try switching to a public DNS server.

# macOS: change DNS to Google and Cloudflare
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 1.1.1.1
 
# Verify it worked
nslookup api.anthropic.com

On Linux, edit /etc/resolv.conf to add nameserver 8.8.8.8, or configure your systemd-resolved settings. A temporary switch to public DNS instantly tells you whether your current DNS server is the problem.

Frequent timeouts

If requests consistently time out, check network quality before changing any code.

# Check packet loss and latency
ping -c 10 api.anthropic.com
# Watch for packet loss > 5% or RTT > 500ms
 
# Find where the connection is degrading
traceroute api.anthropic.com 2>/dev/null || tracepath api.anthropic.com

High packet loss or latency usually means the underlying network connection is the issue — try switching to a wired connection or restarting your Wi-Fi router.

SSL/TLS certificate errors

TLS errors can appear even on home networks, not just corporate ones.

# Verify the SSL certificate chain
openssl s_client -connect api.anthropic.com:443 2>&1 | grep -E "Verify|error|OK"
# Expected: Verify return code: 0 (ok)
 
# Check Node.js version — older versions may have TLS incompatibilities
node --version
# Node.js 18 or later is recommended

If you see CERT_UNTRUSTED or UNABLE_TO_VERIFY_LEAF_SIGNATURE, update your system CA certificate bundle.

# macOS
brew install ca-certificates
 
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install --reinstall ca-certificates

Corporate Network and VPN Issues

If Claude Code works at home but not at the office, the first two things to check are HTTP proxy settings and VPN.

# Check current proxy settings
echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
 
# Set proxy for Claude Code if needed
export HTTPS_PROXY=http://proxy.your-company.com:8080
export HTTP_PROXY=http://proxy.your-company.com:8080
export NO_PROXY=localhost,127.0.0.1
 
# Test the proxied connection
curl -x http://proxy.your-company.com:8080 https://api.anthropic.com/v1/models \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -w "\nHTTP Status: %{http_code}\n"

If your company uses a VPN, Claude Code traffic may be routed through it, which can cause slowdowns or outright blocks if api.anthropic.com isn't in the allowed list. Try turning off VPN temporarily — if it fixes the issue, the VPN configuration needs to exclude Anthropic's API endpoints.

Add proxy settings to your shell profile so they persist:

# Add to ~/.bashrc or ~/.zshrc
echo 'export HTTPS_PROXY=http://proxy.your-company.com:8080' >> ~/.zshrc
echo 'export HTTP_PROXY=http://proxy.your-company.com:8080' >> ~/.zshrc
source ~/.zshrc

Recovering a Session After a Network Error

If a network error interrupts a long-running task, you don't always have to start over. Claude Code has session recovery features worth trying first.

# Continue the most recent conversation
claude --continue
 
# Resume a specific session
claude --resume
 
# View available sessions
claude sessions list 2>/dev/null

In environments with unstable networks, it's also practical to break large tasks into smaller chunks rather than issuing one big instruction. Smaller steps are easier to resume from if the connection drops.

Quick Checklist When Nothing Works

If you've gone through all the above and Claude Code is still failing:

# 1. Update Claude Code to the latest version
npm update -g @anthropic-ai/claude-code
 
# 2. Reset the config (in case it's corrupted)
mv ~/.claude ~/.claude.backup
claude  # Starts fresh with a new config
 
# 3. Verify Node.js version
node --version  # 18+ recommended
# nvm users:
nvm use 20
 
# 4. Enable debug logging to see exactly what's failing
ANTHROPIC_LOG=debug claude "test message" 2>&1 | head -50

The debug output includes details about each API request and response, making it much easier to spot where things are going wrong.

When Claude Code won't connect, start with Anthropic's status page and a direct curl to the API endpoint. Those two steps will tell you whether the issue is upstream or in your local setup, and that distinction alone eliminates most of the guesswork. If you're on a corporate network, check your proxy settings and VPN before reaching out to IT — it'll make that conversation much more productive.