Claude Code ECONNRESET, "연결 끊김", "API 응답 대기 중 · 네트워크를 확인하세요", "API에 연결할 수 없음" 및 인증서 오류

오류 메시지

API Error: Connection dropped (ECONNRESET)
API Error: Connection lost mid-response
API Error: fetch failed
Unable to connect to API (ConnectionRefused)
Retrying in 0s · attempt 1/10
Waiting for API response · will retry in 2m 35s · check your network
API Error: Socket is closed
SSL certificate verification failed: unable to get local issuer certificate
Error: certificate has expired (CERT_HAS_EXPIRED)

내 쪽 문제인가요, 서비스 쪽 문제인가요? 2분 점검

curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://api.anthropic.com/v1/models -H "x-api-key: x" -H "anthropic-version: 2023-06-01"
# 401 in under a second = network path is fine, the problem is upstream or in Claude Code
# timeout / SSL error / 000 = the problem is on your side of the wire
env | grep -i -E "proxy|anthropic|node_extra|ssl"
claude --debug     # per-request timing and retry reasons in the log

curl이 빠르게 401 응답을 받고 프록시 변수가 없다면 거의 확실히 업스트림 장애입니다. 다음 이슈가 이 유형에 해당합니다: #87424 (미해결: 데스크톱 앱과 CLI에서 간헐적인 ECONNRESET 발생, VPN과 프록시 없음, 13년 8월부터 발생하여 21년 8월까지 여러 사용자가 확인) 및 #86473 (API에 직접 보내는 HTTP 요청은 정상 작동하지만 모든 환경에서 ECONNRESET가 지속됨). 이런 문제는 로컬에서 해결할 수 없으며, 재시도와 시간이 필요합니다. status.claude.com를 확인하고, 여러 사용자가 이슈 트래커에서 같은 시간대의 문제를 보고한다면 디버깅을 중단하세요.

"API 응답 대기 중 · 네트워크를 확인하세요"

이 메시지는 네트워크를 원인으로 지목하지만, 실제 원인은 다른 경우가 많습니다. #82155 (미해결, 반응 15개): 네트워크가 정상임이 입증되었는데도 하루 종일 수 분씩 멈추고 재시도 대기 시간이 2분을 넘었습니다. #76555 (미해결): 모든 모델에서 매 응답마다 대기 현상이 발생합니다. #72059 및 #70534: 특히 자문 모델을 호출할 때 같은 멈춤 현상이 발생하고, 타이머가 끝난 뒤 정상 응답이 나옵니다. 재시도 대기 시간은 지수적으로 늘어나므로, 눈에 띄는 피해는 실패 자체보다 기다리는 시간입니다. 아래 변수로 이를 줄일 수 있습니다.

재시도 및 시간 초과 변수

export CLAUDE_CODE_MAX_RETRIES=15               # default 10, capped at 15
export CLAUDE_CODE_RETRY_WATCHDOG=1              # keep retrying instead of giving up (unattended runs)
export API_TIMEOUT_MS=600000                     # per-request timeout, default 10 minutes
export CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000 # give up on a silent stream sooner and retry
export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=2    # fewer parallel streams on a flaky link

첫 바이트 수신 시간 제한을 낮추면 불안정한 연결에서의 체감이 달라집니다. 응답이 오지 않을 스트림에서 10분 내내 기다리는 대신 클라이언트가 해당 스트림을 포기하고 재시도합니다. 여러 스트림이 동시에 실행될 때 연결이 끊기는 환경(모바일 핫스폿, 일부 VPN)에서는 도구 사용의 동시 실행 수를 낮추는 것이 도움이 됩니다.

프록시, VPN 및 기업 네트워크

Claude Code가 읽는 프록시 변수를 설정하세요: HTTPS_PROXY (및 HTTP_PROXY, NO_PROXY). 브라우저나 npm 설정에만 있는 프록시는 CLI에서 인식되지 않습니다.
TLS 검사 프록시 는 Anthropic의 인증서를 자체 인증서로 바꿉니다. 이것이 다음 오류의 원인입니다: unable to get local issuer certificate. 기업 루트 CA를 PEM 파일로 내보내고 다음을 설정하세요: NODE_EXTRA_CA_CERTS=/path/to/corp-root.pem. 인증서 검증을 비활성화하지 마세요.
네이티브 빌드에서 `CERT_HAS_EXPIRED` 발생 (#71727, 2.1.19x): 시스템 시계가 아니라 번들로 제공되는 신뢰 저장소 문제입니다. claude update; 해결되지 않으면 시스템 저장소를 사용하는 npm 빌드를 이용하세요.
macOS에서 재설치 후 `ConnectionRefused` 발생 (#75897) — 로컬 프록시나 VPN 클라이언트가 꺼져 있지만 환경에는 여전히 설정되어 있는 경우입니다. 프록시 변수와 시스템 프록시 설정을 지운 다음 다시 시도하세요.
VPN 출구 변경 은 세션 도중 열려 있는 모든 스트림을 재설정합니다. 다시 연결할 때마다 ECONNRESET가 한 번 발생할 수 있습니다.

게이트웨이를 통한 연결

Claude Code가 게이트웨이를 사용하도록 설정하면(ANTHROPIC_BASE_URL=https://aiprimetech.io) 네트워크 경로가 달라집니다. 클라이언트는 게이트웨이와 통신하고, 게이트웨이는 업스트림 연결을 유지하며 한 계정이 포화 상태가 되면 다른 계정으로 재시도합니다. 로컬 네트워크 장애를 해결해 주지는 않지만, 위에서 설명한 *업스트림 연결 재설정*을 겪는 사용자에게는 단일 계정에 대한 의존성을 없애 주며, 구독 관련 장애가 발생해도 같은 키를 계속 사용할 수 있습니다. 전환하기 전에 게이트웨이 호스트에 대해 curl 검사를 실행하여 경로를 확인하세요.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_gateway_key
claude

이 문제와 씨름하는 데 지치셨나요?

대신 AI Prime Tech 게이트웨이를 통해 Claude Code를 실행하세요. 게이트웨이 자체 업스트림 계정에서 동일한 Claude 모델을 사용하며, 환경 변수 두 개로 전환할 수 있고, 신규 계정에는 다음이 제공됩니다: $5의 무료 API 크레딧이 제공됩니다 사용할 코드: FIXIT — 카드 불필요.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

코드 FIXIT로 계정 만들기

자주 묻는 질문

Claude Code에서 'API 오류: 연결이 끊어졌습니다(ECONNRESET)'를 어떻게 해결하나요?

API에 대해 curl을 실행하세요. 응답이 빠르고 프록시를 사용하지 않는다면 업스트림에서 연결이 재설정된 것입니다. 재시도가 진행되도록 두고 status.claude.com.을 확인하세요. curl도 실패한다면 프록시 변수, VPN 또는 CA 인증서 문제를 해결하세요.

'API 응답 대기 중 · … 후 재시도 · 네트워크를 확인하세요'는 무슨 뜻인가요?

Claude Code가 제한 시간 내에 API 응답을 받지 못해 재시도 전에 대기하고 있다는 뜻입니다. 문구와 달리 사용자 네트워크 문제가 아닌 경우가 많습니다. 클라이언트가 응답 없는 스트림을 더 빨리 포기하도록 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS 값을 낮추세요.

Claude Code에서 '로컬 발급자 인증서를 가져올 수 없습니다'를 어떻게 해결하나요?

프록시가 TLS 인증서를 다시 서명하고 있습니다. 회사의 루트 인증서를 PEM 형식으로 내보내고 NODE_EXTRA_CA_CERTS을 해당 파일로 설정하세요. 인증서 검증을 비활성화하지 마세요.

'0초 후 재시도 · 시도 1/10'는 무슨 뜻인가요?

요청이 실패하여 Claude Code가 재시도하고 있다는 뜻입니다. 기본적으로 대기 시간을 늘리며 10회 시도합니다. CLAUDE_CODE_MAX_RETRIES을 사용하면 시도 횟수가 15회로 늘어나며, CLAUDE_CODE_RETRY_WATCHDOG=1로 설정하면 무인 실행 시 계속 재시도합니다.

게이트웨이에서 Claude Code 실행하기

동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 FIXIT로 $5의 무료 API 크레딧을 받으세요.

API 키 발급받기 무제한 요금제 보기

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.

Claude Code 연결 오류: ECONNRESET, 응답 도중 연결 끊김, "API 응답 대기 중", "API에 연결할 수 없음", SSL 인증서 오류

TLDR