Unable to connect to API는 Claude Code가 현재 API route까지 TCP 연결을 완료하지 못했다는 뜻입니다. 서버가 401, 429, 500, 529를 반환한 상태와는 다릅니다. 먼저 실시간 Claude Status를 확인하고, Claude Code를 실행한 같은 shell에서 다음 명령을 실행하세요.
bashcurl -I https://api.anthropic.com
curl도 연결되지 않으면 해당 환경의 DNS, firewall, VPN, proxy, TLS를 확인합니다. curl은 HTTP response를 받는데 Claude Code만 실패하면 /status, proxy/CA 환경 변수, WSL 또는 macOS, Docker, ANTHROPIC_BASE_URL이 가리키는 실제 host를 확인합니다.
| 오류 suffix | 좁혀지는 원인 | 첫 확인 |
|---|---|---|
ECONNREFUSED | 대상 host나 local proxy가 연결을 거부 | 실제 endpoint와 proxy 주소 |
ECONNRESET | 연결 후 VPN, proxy, network device 또는 remote side가 reset | 다른 신뢰 가능한 network로 한 번 비교 |
ETIMEDOUT | 제한 시간 안에 연결 경로가 완성되지 않음 | DNS, firewall, proxy, route latency |
fetch failed | 정상 API response 전 network layer 실패 | 다음 오류 줄과 same-shell test |
| certificate / self-signed certificate | TLS inspection 또는 corporate CA 누락 | 승인된 CA bundle 설정 |
| HTTP status와 JSON body | API 또는 provider가 응답함 | 연결 분기를 끝내고 status별 처리 |
Claude Code 재설치, key 교체, VPN/DNS 변경, model 변경을 동시에 하지 마세요. 여러 항목을 바꾼 뒤 우연히 성공하면 원인을 알 수 없고 재발을 막을 수도 없습니다.
먼저 순수한 연결 오류인지 확인하기
Anthropic의 Claude Code 오류 참조는 Unable to connect to API, ECONNREFUSED, ECONNRESET, ETIMEDOUT, fetch failed, network/proxy 문구가 포함된 timeout을 network error로 분류합니다. 실무 경계는 HTTP response가 있었는지입니다.
- status code, response body, request ID가 없다면 connection path를 계속 봅니다.
401또는 invalid key가 반환되면 network는 API layer에 도달한 것이므로 authentication을 확인합니다.429,500,529가 반환되면 API나 설정된 provider가 응답한 것이므로 해당 status를 처리합니다.Connection closed mid-response가 나오면 streaming이 시작된 상태입니다. 완성된 output block은 남기고 마지막 정상 지점부터 이어가세요.
Claude Code는 여러 일시적 connection failure와 server error를 자동으로 exponential backoff 재시도합니다. 최종 오류가 터미널에 보인다면 짧은 자동 복구가 문제를 없애지 못했다는 뜻입니다. 같은 조건으로 계속 재시도하는 것은 진단에 도움이 되지 않습니다.
Claude Code를 시작한 같은 shell에서 테스트하기
browser, WSL, SSH, VS Code Remote, container는 서로 다른 DNS, proxy, certificate store를 사용할 수 있습니다. 브라우저에서 claude.ai가 열린다고 해서 claude process가 api.anthropic.com에 접근할 수 있는 것은 아닙니다.
host 연결과 route 관련 변수만 확인합니다.
bashcurl -I https://api.anthropic.com env | grep -Ei '^(ANTHROPIC_BASE_URL|ANTHROPIC_API_KEY|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|NODE_EXTRA_CA_CERTS)='
API key나 proxy password가 출력된다면 issue, 채팅, 화면 캡처에 붙여 넣지 마세요. 변수의 존재 여부와 선택된 host, proxy, certificate path만 확인하면 됩니다.
| curl 결과 | Claude Code 결과 | 우선 확인할 owner |
|---|---|---|
| host resolve 실패 | 실패 | DNS 또는 WSL resolver |
| port 443 timeout | 실패 | Firewall, VPN, proxy, outbound route |
| certificate validation error | 실패 | TLS inspection과 CA trust |
| 어떤 HTTP response든 수신 | 연결 오류 | Claude Code process environment, settings scope, gateway |
| response 수신 | 401/429/500/529 | 순수한 connection error가 아님 |
curl -I 성공은 host의 기본 reachability만 보여 줍니다. account, full request, model, gateway compatibility까지 검증하는 end-to-end test는 아닙니다.
curl도 실패하면 network path 수정하기
status page가 green이라고 해서 모든 지역, ISP, 회사 network가 정상이라는 뜻은 아닙니다. 그다음 하나의 조건만 바꿔 비교하세요.
- 모바일 hotspot이나 가정 network 같은 다른 신뢰 가능한 연결에서 같은 curl을 한 번 실행합니다.
- VPN이 켜져 있다면 한 번의 비교를 위해 끕니다. 회사 정책상 VPN이 필수라면 우회하지 말고 network team에 allowlist 확인을 요청하세요.
- 실제 API host와 공식 network access requirements의 주소가 firewall에서 허용되는지 확인합니다.
- Linux/WSL은
/etc/resolv.conf의 nameserver가 실제로 도달 가능한지 봅니다. Windows 브라우저가 정상이어도 WSL resolver는 실패할 수 있습니다. - DNS는 성공하지만 443이 timeout이면 credential이 아니라 firewall, router, proxy, outbound route를 점검합니다.
ECONNREFUSED는 실제 host 또는 local proxy port가 연결을 거부했을 때 흔합니다. ANTHROPIC_BASE_URL이 예상하지 않은 host를 선택하지 않았는지 확인하세요. ECONNRESET은 연결 후 reset된 경우이므로 VPN, TLS inspection appliance, 불안정한 network, long-lived connection policy가 더 중요한 후보입니다.
Corporate proxy와 custom CA 함께 설정하기
Claude Code는 시작할 때 표준 proxy 변수를 읽습니다.
bashexport HTTPS_PROXY=https://proxy.example.com:8080 export NO_PROXY=".example.internal" claude
scheme, host, port는 조직이 제공한 값을 사용해야 합니다. Claude Code는 SOCKS proxy를 지원하지 않습니다. proxy가 TLS inspection을 수행한다면 승인된 CA bundle을 지정합니다.
bashexport NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem claude
NODE_TLS_REJECT_UNAUTHORIZED=0을 사용하면 certificate verification 전체가 꺼지므로 해결책이 아닙니다. proxy credential을 repository script에 저장하지도 마세요. shell, Desktop-managed, cloud, background session의 scope 차이는 공식 enterprise network configuration에서 확인할 수 있습니다.
Claude Code가 시작된 뒤 export한 변수는 실행 중 process에 반영되지 않습니다. proxy 또는 CA를 바꾼 뒤 재시작하세요. Desktop-managed session이나 background supervisor는 현재 shell 변수를 읽지 않을 수 있으므로 /status와 debug log에서 실제 로드 결과를 확인합니다.
curl은 성공하지만 Claude Code만 실패할 때
Claude Code에서 /status를 실행하고 active credential, provider, proxy, endpoint가 의도와 같은지 확인합니다.
- 예상하지 않은 API key:
ANTHROPIC_API_KEY가 있으면 subscription login 대신 API-key route를 선택할 수 있습니다. secret 값은 출력하지 마세요. - 예상하지 않은 gateway:
ANTHROPIC_BASE_URL은 destination을 바꿉니다. official API와 third-party relay는 서로 다른 owner를 가진 별도 시스템입니다. - WSL 또는 remote IDE: host terminal, WSL, 실제 VS Code Remote shell에서 같은 curl을 실행해 DNS, proxy, CA 차이를 비교합니다.
- macOS의 오래된 VPN route: 연결 해제나 삭제 후에도
utuninterface 또는 network extension이 남을 수 있습니다. System Settings에서 확인하고 모르는 route를 임의 삭제하지 마세요. - Docker Desktop: container runtime이 outbound traffic을 가로챌 수 있습니다. 작업에 안전할 때만 종료한 상태로 한 번 비교합니다.
- Background process: supervisor가 다른 shell의 오래된 environment를 상속했을 수 있습니다. 필요한 network variable을 지원되는 user 또는 managed settings scope에 둡니다.
어떤 authentication이나 provider가 우선하는지 불분명하다면 Claude Code API configuration에서 route를 먼저 정리하세요.
작은 request로 복구 확인하기
하나를 바꾼 뒤 Claude Code를 재시작하고 민감한 정보가 없는 짧은 request를 보냅니다. 다음 세 항목이 모두 맞아야 복구입니다.
- 같은 shell이 official host 또는 승인된 gateway에서 HTTP response를 받습니다.
/status가 의도한 authentication과 route를 보여 줍니다.- 새 request가 같은 connection error 없이 완료됩니다.
오류가 HTTP status로 바뀌었다면 transport route가 API layer까지 도달한 것입니다. 실제 응답에 따라 Claude Code API Error 500, Claude API 529 overloaded, Claude API rate limit로 이동하세요. 서버가 응답한 뒤에는 이유 없이 network를 계속 바꿀 필요가 없습니다.
Support packet은 작고 안전하게 만들기
시간과 timezone, OS, Claude Code version, 정확한 error suffix, route type, curl -I 결과, status page 관찰, network나 proxy 한 가지를 바꾼 결과를 기록합니다. ANTHROPIC_BASE_URL host는 private address가 아닐 때만 공유합니다.
API key, OAuth token, proxy password, private prompt, customer data, 전체 environment dump는 보내지 마세요. official route는 Help Center 또는 사용 가능한 /feedback, corporate network나 gateway는 실제 platform owner에게 같은 redacted packet을 전달합니다.
판단 규칙은 간단합니다. 같은 shell의 curl도 실패하면 host까지의 path를, curl은 성공하고 Claude Code만 실패하면 process environment를, HTTP error가 반환되면 connection이 아닌 response를 수정합니다.
