클로드 코드 api 에러 — 코드별 원인과 해결
클로드 코드에서 뜨는 API 에러는 숫자만 보면 어느 쪽 잘못인지 바로 갈립니다. 500·529는 서버가 아파서 나는 것이라 내가 고칠 게 없고, 429는 한도나 요청량 문제, 401은 인증 문제라 /login이나 ANTHROPIC_API_KEY를 손봐야 합니다. 아래는 공식 Error reference 원문을 기준으로 코드별 원인과 대처를 정리한 것입니다. (Claude Code 2.1.202 기준 · 2026년 8월 5일 문서 확인)
1. 에러 코드 한눈에 보기
터미널에 뜬 문구에서 숫자만 찾으면 됩니다. 클로드 코드는 모델 응답을 받으려고 Claude API를 호출하기 때문에, 런타임 에러 대부분이 그 아래의 API 에러 코드로 이어집니다.
| 코드 | 뜻 | 누구 잘못인가 | 먼저 할 일 |
|---|---|---|---|
| 500 | API 내부 오류 | 서버 | 잠시 뒤 재시도 · 상태 페이지 확인 |
| 529 | 과부하(용량 소진) | 서버 | /model로 다른 모델 전환 |
| 429 | 요청 제한(레이트 리밋) | 내 키·프로젝트 설정 | /status로 쓰는 자격증명 확인 |
| 401 | 인증 거부 | 내 계정·키 | /status → /login 또는 키 교체 |
| 400 | 요청 자체가 잘못됨 | 대화 길이·첨부 | /compact로 컨텍스트 정리 |
2. 500 · 529 — 서버 쪽 문제라 내가 고칠 게 없다
5xx 응답이 오면 클로드 코드는 상태 코드와 API가 준 메시지를 그대로 보여줍니다. Anthropic API를 쓸 때의 500 응답은 이렇게 뜹니다.
API Error: 500 Internal server error. This is a server-side issue,
usually temporary — try again in a moment. If it persists,
check https://status.claude.com.공식 문서는 이 에러를 두고 "프롬프트·설정·계정 때문에 생기는 것이 아니다"라고 못박습니다. 즉 내 CLAUDE.md나 권한 설정을 뒤질 이유가 없습니다. 할 일은 셋뿐입니다.
- status.claude.com에서 진행 중인 장애가 있는지 본다
- 1분쯤 기다렸다 다시 보낸다 — 원래 메시지는 대화에 그대로 남아 있으므로, 긴 프롬프트라면 전부 다시 붙여넣지 말고
try again이라고만 쳐도 된다 - 공지된 장애가 없는데도 계속 나면
/feedback으로 요청 정보를 함께 보낸다
529는 성격이 조금 다릅니다. 전체 사용자 기준으로 API 용량이 찬 상태고, 메시지에 Repeated가 붙는 것에서 알 수 있듯 이미 여러 번 재시도한 뒤에 나옵니다.
API Error: Repeated 529 Overloaded errors. The API is at capacity —
this is usually temporary. Try again in a moment. If it persists,
check https://status.claude.com.여기서 중요한 게 두 가지입니다. 첫째, 529는 내 사용량 한도가 아니며 할당량을 깎지도 않습니다. 요금제 한도에 걸린 걸로 오해하고 클로드 코드 요금제를 올릴 필요가 없다는 뜻입니다. 둘째, 용량은 모델별로 따로 잡힙니다. 그래서 /model로 다른 모델로 갈아타면 그대로 작업을 이어갈 수 있고, 실제로 한 모델에 부하가 몰리면 클로드 코드가 먼저 이렇게 권합니다.
Opus is experiencing high load, please use /model to switch to Sonnet3. 429 — 이름이 비슷한 세 가지를 구분해야 한다
"요청이 막혔다"로 보이는 메시지가 셋인데 원인이 전부 다릅니다. 여기서 헷갈리면 엉뚱한 곳을 고치게 됩니다.
| 메시지 | 정체 | 대처 |
|---|---|---|
You've hit your session limitYou've hit your weekly limit |
구독 요금제 사용량 소진 | 메시지에 찍힌 초기화 시각까지 대기 |
You've hit your Opus limit |
Opus 전용 한도만 소진 | /model로 다른 모델 전환 |
Request rejected (429) |
API 키·프로젝트에 걸린 레이트 리밋 | /status로 자격증명 확인, 동시 요청 줄이기 |
Server is temporarily limiting requests |
요금제와 무관한 서버 측 일시 스로틀 | 잠깐 기다렸다 재시도 |
세션·주간 한도는 모델 전체가 같이 쓰는 한도라 모델을 바꿔도 풀리지 않습니다. 반면 Opus 한도는 Opus 요청에만 걸리므로 /model 한 줄로 계속 일할 수 있습니다. 지금 얼마나 남았는지는 클로드 코드 사용량 확인 방법대로 /usage로 미리 보는 편이 낫습니다.
Request rejected (429)는 성격이 완전히 다릅니다. 이건 구독 한도가 아니라 API 키나 Bedrock·Google Cloud 프로젝트에 설정된 레이트 리밋입니다. 공식 문서가 첫 번째로 시키는 게 /status인 이유가 있습니다.
ANTHROPIC_API_KEY 하나 때문에 429가 나는 경우가 많습니다. 구독으로 로그인했다고 생각했는데 낮은 등급의 API 키로 요청이 나가고 있는 것입니다. /status에 API key 줄이 보이면 그게 범인입니다.
# 지금 셸에 키가 남아 있는지 확인
env | grep ANTHROPIC
# 키를 걷어내고 구독 로그인으로 돌아가기
unset ANTHROPIC_API_KEY키가 맞는데도 계속 429가 나면 요청량 자체를 줄입니다. 병렬로 도는 읽기 도구와 서브에이전트 수는 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY(기본값 10)로 조절할 수 있고, 대량 스크립트 작업이라면 /model로 더 작은 모델을 쓰는 것도 문서가 권하는 방법입니다.
4. 401 — 만료가 아니라 "거부"다
401에서 가장 자주 헷갈리는 지점입니다. 공식 문서는 이 에러를 두고 자격증명이 만료된 경우가 아니라고 분명히 적습니다. 방금 취소된 키, 비활성화된 조직, 접근 권한이 회수된 계정일 때 나옵니다.
Please run /login · API Error: 401 Invalid authentication credentials메시지가 /login을 권하지만, 그것만으로 안 풀리는 경우가 있습니다. 승인된 ANTHROPIC_API_KEY가 있으면 그 키가 로그인보다 우선하기 때문에, /login을 다시 해도 활성 자격증명이 바뀌지 않습니다. 그래서 순서가 /status 먼저입니다.
/status에API key줄이 있다 → 콘솔에서 키를 교체하거나unset ANTHROPIC_API_KEY- 로그인만 보인다 →
/login을 한 번 실행하면 취소된 자격증명이 새것으로 교체된다 - 같은 계정으로 다시 해도 똑같다 → 계정이나 조직 자체가 비활성 상태다. 조직 관리자에게 확인한다
인증 계열에서 401과 자주 헷갈리는 게 Login expired입니다. 이건 API가 준 응답이 아니라, 저장된 로그인 갱신에 실패해서 클로드 코드가 스스로 자격증명을 지운 상태입니다. 요청이 아예 나가지 않으므로 /login 말고는 방법이 없습니다.
# 대화형 세션
Login expired · Please run /login
# -p 헤드리스 · Agent SDK (구조화 에러 코드: authentication_failed)
Failed to authenticate: OAuth session expired and could not be refreshed5. 400 계열 — 대화가 너무 길거나 요청이 너무 크다
요청 내용 때문에 거절되는 경우입니다. 둘은 이름이 비슷해도 걸리는 한도가 완전히 다릅니다.
| 메시지 | 걸린 한도 | 대처 |
|---|---|---|
Prompt is too long |
모델 컨텍스트 윈도우(토큰) | /compact · /clear · /context로 원인 확인 |
Request too large (max 32MB) |
HTTP 요청 본문 크기(32MB) | 첨부·이미지 정리, 파일은 경로로 넘기기 |
Prompt is too long이 떴다면 /context부터 열어 무엇이 창을 먹고 있는지 봅니다. 시스템 프롬프트·도구 정의·메모리 파일·메시지로 나눠 보여주는데, 의외로 안 쓰는 MCP 서버의 도구 정의가 크게 잡히는 일이 많습니다. /mcp disable <이름>으로 끄면 그만큼 컨텍스트가 빕니다. 서브에이전트는 부모 세션의 MCP 도구 정의를 전부 물려받으므로, 정리하지 않고 띄우면 첫 턴도 못 가서 창이 찹니다. 정리 명령의 차이는 클로드 코드 컨텍스트 관리 글에서 /compact와 /clear를 갈라 두었습니다.
/compact를 돌렸는데 그마저 실패하는 경우도 있습니다. 요약을 담을 여유 공간조차 없을 때입니다. 이때는 Esc를 두 번 눌러 메시지 목록에서 몇 턴 뒤로 물러난 다음 다시 /compact를 돌리라고 문서가 안내합니다.
Error during compaction: Conversation too long.
Press esc twice to go up a few messages and try again.6. 자동 재시도 — 무엇을 다시 시도하고 무엇을 안 하나
클로드 코드는 일시적 실패를 지수 백오프로 최대 10회 재시도합니다. 재시도 중에는 스피너에 Retrying in Ns · attempt x/y 카운트다운이 뜹니다. 무엇을 재시도하는지가 갈려 있습니다.
| 재시도한다 | 재시도하지 않는다 |
|---|---|
| 서버 에러·과부하 응답·요청 타임아웃 | TLS 인증서 검증 실패(중간자 프록시, 만료된 인증서 등) |
| 응답이 시작되기 전에 끊긴 연결 | 응답 도중(텍스트·도구 호출을 이미 끝낸 뒤) 발생한 서버 에러 |
| 일시적인 429 스로틀 | Bedrock 스트리밍 응답의 content-type이 어긋난 경우 |
응답 도중 끊긴 걸 다시 보내지 않는 이유가 재미있습니다. 같은 도구 호출을 두 번 실행할 수 있기 때문입니다. 그래서 클로드가 끝낸 부분은 남겨 두고 이런 안내만 덧붙입니다.
API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection closed mid-response. The response above may be incomplete.
API Error: Response stalled mid-stream. The response above may be incomplete.이때는 continue라고 답하면 마지막으로 끝낸 블록부터 이어서 갑니다.
재시도 동작은 환경변수로 조절합니다. CI처럼 사람이 안 보는 환경이라면 CLAUDE_CODE_RETRY_WATCHDOG를 켜는 쪽이 문서가 권하는 방법입니다.
| 환경변수 | 기본값 | 쓰임 |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES |
10 | 재시도 횟수. v2.1.186부터 상한 15. 스크립트에서 빨리 실패시키려면 낮춘다 |
CLAUDE_CODE_RETRY_WATCHDOG |
없음 | 1로 두면 429·529를 무한 재시도(최대 5분 간격 백오프). CI·무인 세션용 |
API_TIMEOUT_MS |
600000 (10분) | 요청당 타임아웃. 느린 망·프록시에서 올린다. 최대 2147483647 |
# mac / Linux — 타임아웃을 20분으로 올리고 CI에서 무한 재시도
export API_TIMEOUT_MS="1200000"
export CLAUDE_CODE_RETRY_WATCHDOG=1
# 값이 실제로 잡혔는지 확인
echo $API_TIMEOUT_MSAPI_TIMEOUT_MS에 최대값(2147483647)보다 큰 수를 넣으면 내부 타이머가 오버플로해서 요청이 즉시 실패합니다. "넉넉하게" 큰 수를 박아 넣지 마세요.
자주 묻는 질문 (FAQ)
Q. 529가 계속 뜨는데 요금제를 올리면 해결되나요?
아닙니다. 529는 전체 사용자 기준으로 API 용량이 찬 것이고, 공식 문서도 내 사용량 한도가 아니며 할당량을 깎지 않는다고 명시합니다. 용량은 모델별로 관리되므로 /model로 다른 모델로 옮기는 게 실질적인 우회책입니다.
Q. /login을 다시 했는데도 401이 그대로입니다.
승인된 ANTHROPIC_API_KEY가 환경에 있으면 그 키가 로그인보다 우선합니다. /status에 API key 줄이 보이는지 먼저 확인하고, 그렇다면 키를 교체하거나 unset ANTHROPIC_API_KEY 후 다시 시도하세요.
Q. 에러 없이 응답만 이상할 때는요?
공식 Error reference에 "Responses seem lower quality than usual" 항목이 따로 있습니다. 에러 코드가 안 뜨는 상황도 문서에서 다루므로, 증상만 있고 메시지가 없을 때도 같은 페이지를 먼저 보면 됩니다.
Q. 설치할 때 나는 command not found도 여기서 찾나요?
아닙니다. 설치·로그인 단계의 오류는 별도 문서(Troubleshoot installation and login)로 갈라져 있습니다. 설치 단계에서 막혔다면 클로드 코드 설치 글의 실패 사례부터 확인하는 편이 빠릅니다.
마무리
정리하면 숫자 하나로 방향이 갈립니다. 500·529는 서버 쪽이라 기다리거나 모델을 바꾸고, 429는 /status로 어떤 자격증명이 쓰이는지부터 보고, 401은 /login 이전에 ANTHROPIC_API_KEY가 가로채고 있는지 확인합니다. 400 계열은 /context로 무엇이 창을 먹는지 보는 게 시작입니다.
에러 메시지는 버전마다 문구와 동작이 바뀝니다. 이 글은 Claude Code 2.1.202 기준이며, 지금 쓰는 버전은 claude --version으로 확인하고 최신 문구는 공식 Error reference에서 다시 보는 걸 권합니다.
📚 참고 출처 (2026년 8월 5일 확인)
· Claude Code Docs — Error reference
· Claude Code Docs — Environment variables
· Claude Code Docs — Slash commands
· Claude Platform — Rate limits
· Anthropic Status
COMMENTS