Claude Code를 쓰다 빨간 에러 메시지가 뜨면 덜컥 겁이 날 수 있습니다. 하지만 대부분의 에러는 원인이 정해져 있고, 메시지만 차분히 읽으면 스스로 해결할 수 있습니다. 이 글은 처음 쓰는 분을 위해 "에러 메시지를 어떻게 읽고, 어떤 종류인지 가려내고, 무엇을 하면 되는지"를 쉽게 설명합니다.
먼저: 에러는 '이미 여러 번 시도한 뒤'에 보입니다
가장 중요한 사실부터. Claude Code는 일시적인 문제(서버 혼잡, 응답 지연, 연결 끊김 등)는 알아서 다시 시도합니다. 공식 문서에 따르면 이런 경우 최대 10번까지 자동 재시도하며, 그동안 화면에는 Retrying in Ns · attempt x/y(N초 후 재시도, 몇 번째 시도인지) 같은 표시가 나타납니다.
즉, 여러분이 보는 에러 메시지는 자동 재시도까지 모두 실패한 뒤에 나오는 것입니다. 그러니 당황하지 말고, 메시지를 '읽는 것'부터 시작하면 됩니다.
에러는 크게 5가지로 나뉩니다
에러 메시지를 보면 먼저 "이게 내 문제인가, 서버 문제인가"부터 가려보세요. 공식 문서는 에러를 대략 다음 5가지로 구분합니다.
① 서버 문제 (내 탓이 아님)
Anthropic 서버 쪽 문제로, 내 계정이나 요청과는 무관합니다. 대표적으로 500 Internal server error(서버 내부 오류)와 Repeated 529 Overloaded errors(서버가 일시적으로 너무 붐빔)가 있습니다. 529는 내 사용량 한도와 무관하며 할당량을 깎지도 않습니다.
할 일: status.claude.com에서 장애 공지를 확인하고, 잠시 뒤 다시 보내세요(긴 프롬프트는 전체를 다시 붙여넣지 말고 "다시 시도"라고만 입력해도 됩니다). 한 모델이 붐비면 /model로 다른 모델로 바꿔 계속 작업할 수 있습니다.
② 사용량 한도
내 구독 플랜의 사용 할당량에 도달한 경우입니다. You've hit your session limit · resets 3:45pm(세션 한도, 리셋 시각 표시)처럼 나옵니다. 서버 문제와 달리 이건 내 계정에 한정됩니다.
할 일: 메시지에 표시된 리셋 시각까지 기다리거나, /usage로 남은 한도를 확인하세요. Pro·Max에서는 /extra-usage로 추가 사용을 구매할 수도 있습니다.
③ 로그인(인증) 문제
Claude Code가 "내가 누구인지" 확인하지 못하는 경우입니다. Not logged in · Please run /login(로그인 안 됨), Invalid API key(잘못된 API 키) 등이 있습니다.
할 일: 먼저 /status로 현재 어떤 인증을 쓰는지 확인하고, /login으로 다시 로그인하세요. 참고로 환경변수 ANTHROPIC_API_KEY가 설정돼 있으면 /login보다 우선합니다. 그래서 구독으로 로그인했는데도 엉뚱한 키로 연결된다면, 그 환경변수를 해제해야 할 수 있습니다.
④ 네트워크(연결) 문제
Claude Code가 API 서버에 아예 닿지 못하는 경우로, 대개 내 쪽 인터넷·프록시·방화벽이 원인입니다. Unable to connect to API(연결 불가)가 대표적입니다.
할 일: 같은 터미널에서 curl -I https://api.anthropic.com을 실행해 서버에 닿는지 확인하세요(윈도우 PowerShell에서는 curl.exe 사용). 회사 프록시 환경이면 HTTPS_PROXY 설정이 필요할 수 있습니다.
⑤ 요청 문제
요청 자체가 너무 크거나 형식이 맞지 않는 경우입니다. 가장 흔한 건 Prompt is too long(대화가 너무 길어 한도 초과)입니다.
할 일: /compact(이전 대화 요약해 공간 확보) 또는 /clear(새로 시작)를 쓰세요. /context로 무엇이 공간을 많이 차지하는지 볼 수 있습니다. 큰 파일은 내용을 붙여넣기보다 경로로 참조하면 Claude가 나눠 읽습니다.
에러가 떴을 때 — 당황 말고 3단계
- 메시지 읽기 — 빨간 글씨를 한 줄 천천히 읽습니다. 보통 무엇이 문제인지 영어로 적혀 있습니다.
- 분류 맞추기 — 위 5가지 중 어디에 해당하는지 가려봅니다(서버/사용량/로그인/네트워크/요청).
- 해당 조치 — 분류에 맞는 조치를 합니다. 재시도, 리셋 대기,
/login,/compact등.
막힐 때 쓰는 도우미
/status— 지금 어떤 계정·인증으로 연결돼 있는지 확인./doctor— 로컬 설정에 문제가 없는지 점검.- status.claude.com — 서버 장애가 있는지 확인.
/feedback— 원인을 모르겠으면 대화 내용과 함께 Anthropic에 신고(일부 제공 환경에서는 비활성).
정리
에러 메시지는 무서운 신호가 아니라 "무엇을 점검하라"는 안내문에 가깝습니다. 핵심은 ① 대부분 자동 재시도 후에 보인다는 것, ② 서버·사용량·로그인·네트워크·요청 5가지로 나뉜다는 것, ③ 메시지를 읽고 분류해 조치하면 된다는 것입니다. 증상별로 더 자세한 해결이 필요하면 같은 사이트의 설치·인증·연결 문제 해결과 느리거나 멈출 때 해결을 이어서 보세요.
본 글은 Anthropic 공식 에러 레퍼런스(code.claude.com/docs/en/errors)의 공개 정보를 초보자용으로 정리했습니다. 에러 메시지·명령은 제품 업데이트로 바뀔 수 있으니 실제 화면과 공식 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.