Claude Code에서 500, 529, 또는 요청 제한처럼 보이는 문구가 나오면, 바로 반복 retry를 하거나 plan을 바꾸지 마세요. 500은 status 확인으로, 반복되는 529는 과부하로, 429나 명확한 usage 문구는 제한 확인으로 가야 합니다.
가장 흔한 함정은 529입니다. Claude Code 문서는 반복 529를 과부하로 설명하며, 개인 사용 한도도 아니고 quota에 잡히는 것도 아니라고 말합니다. 먼저 터미널의 정확한 줄을 아래 분기표에 맞추세요.
| 정확한 문구 | 먼저 볼 분기 | 첫 조치 | 같은 path에서 확인할 것 | 더 깊게 갈 때 |
|---|---|---|---|---|
500 | 서비스 측 내부 오류 | Claude Status 확인, 짧게 대기, 같은 command 한 번 retry | 같은 command, 인증 경로, model | status는 녹색인데 같은 path가 실패 |
반복 529 | capacity overload | status 확인 후 대기; task가 허용할 때만 /model | 같은 session과 경로를 cool-down 후 확인 | status와 경로 확인 뒤에도 반복 |
429 | API key 또는 provider 제한 | 대기 창, Console 한도, model 한도, active API 경로 확인 | window 이후 또는 경로 correction 이후 retry | headers나 Console이 한도 소진을 보임 |
| temporary throttle 문구, session 한도, weekly 한도 | Claude Code throttle 또는 usage window | cool down 또는 plan/session window 확인 | window가 바뀐 뒤 같은 workflow 재개 | 문구가 plan 또는 reset window를 명시 |
| plan과 한도가 계정 예상과 다름 | route override | /status, ANTHROPIC_API_KEY, proxy 확인 | intended subscription/API-key route 확인 | 깨끗한 route에서도 같은 오류 분기 |
원인을 추측하기 전에 분기부터 고른다
Claude Code의 error reference는 runtime error를 Claude API code와 연결합니다. 또한 Claude Code는 일부 transient failure를 사용자에게 보여주기 전에 자동 retry합니다. 그래서 터미널에 보이는 오류 줄은 시작점이 아니라, 자동 retry 이후의 판단 지점입니다.
첫 질문은 "Claude가 다운됐나?"도 아니고 "내 quota가 끝났나?"도 아닙니다. 이 줄이 어떤 문서화된 분기에 속하는지입니다. 500은 status 확인, 짧은 대기, 같은 path retry 한 번으로 시작합니다. 반복 529는 capacity branch입니다. 실제 429는 API key, provider, model limits를 봅니다. session/weekly limit는 usage window입니다. route가 이상하면 /status가 먼저입니다.
2026-04-20 확인 시점에 Claude Status는 Claude API와 Claude Code를 operational로 표시했습니다. 다만 같은 날과 4월 15일의 resolved incidents도 status history에 있었습니다. 이 날짜는 현재 독자의 실패가 로컬 문제라는 증명이 아니라, status 확인 뒤 same-path verification이 필요하다는 경계입니다.
500 분기: status, 짧은 대기, 같은 command 한 번
Anthropic API error docs는 HTTP 500을 api_error로 매핑합니다. Claude Code error reference도 API Error: 500 Internal server error를 infrastructure-side 문제로 다루며 prompt, settings, account가 직접 원인이라고 보지 않습니다.
안전한 순서는 짧습니다.
- Claude Status를 확인합니다.
- 잠깐 기다린 뒤 같은 command 또는 message를 한 번만 retry합니다.
- 검증 중 model, auth route, shell profile, prompt를 동시에 바꾸지 않습니다.
- incident가 없고 같은 path가 계속 실패하면 세부 정보를 보관하고
/feedback또는 support route로 이동합니다.
정확한 증상이 지속적인 API Error: 500이라면 Claude Code API Error 500 가이드로 이어가세요. 여기서는 500을 529나 rate limit처럼 처리하지 않도록 분기만 잡습니다.
529 분기: 과부하이지 usage limit가 아니다
Claude Code 문서는 반복 529를 꽤 명확하게 설명합니다. API가 전체 사용자 단위의 capacity pressure를 받고 있으며, Claude Code가 이미 retry했고, 529는 usage limit도 quota 차감도 아닙니다.
첫 조치는 upgrade가 아닙니다.
- status에서 capacity notice를 확인합니다.
- 몇 분 기다린 뒤 다시 시도합니다.
/model은 task가 다른 model을 받아들일 수 있을 때만 씁니다.- 짧은 cool-down 뒤 같은 session과 route를 확인합니다.
반복 529가 이 확인 뒤에도 돌아오면 Claude Code overloaded error 가이드로 이동하세요. 529 overloaded_error를 429 rate_limit_error처럼 다루면 key, billing, plan 조치로 너무 빨리 가게 됩니다.
요청 제한 분기: 429, temporary limiting, usage window를 분리
Claude Code에서 "제한"처럼 보이는 문구는 최소 세 가지입니다.
첫째는 실제 API 429 rate_limit_error입니다. API key, provider project, model-specific limits, concurrency, retry-after가 증거입니다. 이 경우 Claude Code rate limit 가이드가 맞는 다음 경로입니다.
둘째는 Server is temporarily limiting requests (not your usage limit)입니다. 이는 짧은 throttle로 보고 cool down 뒤 같은 path를 확인합니다. plan이 소진됐다는 증거가 아닙니다.
셋째는 실제 usage window입니다. session limit, weekly limit, Opus limit, reset time이 보이면 /usage, reset timing, plan window를 봅니다. 이어서 rate-limit reached 가이드 또는 usage limits 진단을 사용하세요.
route override 분기: plan보다 auth 확인이 먼저다
Claude Help는 environment variable의 ANTHROPIC_API_KEY가 authenticated subscription보다 우선할 수 있고, /status로 active auth method를 확인할 수 있다고 설명합니다. 그래서 route check는 부가 단계가 아니라 복구 흐름의 일부입니다.
secret을 노출하지 않는 확인만 하세요.
- Claude Code 안에서
/status를 실행합니다. - shell이나 environment에
ANTHROPIC_API_KEY가 설정됐는지만 확인하고 key 자체는 붙여넣지 않습니다. - subscription auth, direct Anthropic API, Bedrock, Vertex, proxy 중 무엇인지 확인합니다.
- 원래 의도한 route에서 같은 request를 다시 실행합니다.
route를 바로잡았을 때 결과가 바뀌면 실제 문제는 route mismatch였습니다. intended route에서도 같은 분기가 계속되면 support evidence가 더 깨끗해집니다.
에스컬레이션 전에 남길 증거
Anthropic API error response에는 top-level request_id가 있을 수 있고, API response에는 request-id header가 있을 수 있습니다. Claude Code에는 /status, /model, /usage, /feedback도 있습니다.
짧게만 보관하면 됩니다.
500,529,429, 또는 제한 문구 전체가 포함된 정확한 터미널 줄- 실패 시간과 timezone
- 그 시점의 Claude Status
/status의 active route- 사용 model과
/model변경 여부 - same-path retry 결과
- request ID 또는 feedback context
분기를 맞추고, 최소 조치를 했고, 같은 path가 여전히 실패하면 멈추세요. 무작위 retry는 evidence를 흐립니다.
자주 묻는 질문
Claude Code 529는 rate limit인가요?
아니요. 반복 529는 overload로 문서화되어 있습니다. 실제 API rate limiting은 429 rate_limit_error이고, temporary limiting과 plan-window wording은 또 다릅니다.
Claude Code API Error 500에서 먼저 무엇을 하나요?
Claude Status를 확인하고, 잠깐 기다린 뒤, 같은 command 또는 message를 한 번 retry합니다. incident가 없고 같은 path가 계속 실패하면 세부 정보를 남기고 500 가이드나 /feedback로 이동합니다.
Claude Status가 녹색인데도 실패하면요?
녹색 status는 공개 live incident 하나를 제외할 뿐입니다. 정확한 error, active auth route, model, same-path retry result는 여전히 확인해야 합니다.
API key가 subscription을 덮어쓰는지 어떻게 보나요?
Claude Code에서 /status를 실행하고 shell에 ANTHROPIC_API_KEY가 설정되어 있는지 확인합니다. key 자체는 붙여넣지 마세요.
529가 나오면 plan을 업그레이드해야 하나요?
첫 조치로는 아닙니다. 반복 529는 overload branch입니다. upgrade 판단은 명확한 plan-limit 또는 usage-window wording일 때만 합니다.