Claude Code가 API Error: 529를 보여주면, 먼저 "내 개인 usage가 다 찼나?"라고 생각하지 않는 편이 맞습니다. Anthropic의 API error docs는 529를 overloaded_error로 정의합니다. 그래서 첫 질문은 plan, billing, upgrade가 아니라 지금 상황이 live incident인지, status는 녹색인데 같은 path만 계속 실패하는지, 실제로는 429를 보고 있는지, 아니면 Claude Code가 예상과 다른 auth route로 요청을 보내고 있는지입니다.
가장 먼저 Claude Status를 확인하세요. 그다음 /status와 environment variables를 함께 보고 Claude Code가 실제로 어떤 route를 쓰고 있는지 확인합니다. status가 녹색이어도 다음 단계가 설정을 대량으로 바꾸는 일은 아닙니다. 같은 path를 유지한 채 짧은 retry나 route check를 한 번 하고, 그 결과만 보는 편이 훨씬 낫습니다.
status와 route를 모두 확인했는데도 같은 path가 계속 529를 반환하면, 그 시점부터는 "로컬에서 조금만 더 손보면 되겠다"는 단계가 아닙니다. 정확한 error text와 request_id를 남기고 깔끔하게 에스컬레이션하세요. Anthropic의 error docs, Claude Code help, status surface는 2026-04-11 기준으로 다시 확인했습니다. 그 시점의 public status는 녹색이었지만, 그렇다고 529 분기가 사라지는 것은 아닙니다. 그저 다음 진단이 더 좁아질 뿐입니다.
30초 분기 보드
API Error: 529는 개념 설명보다 먼저 분기 판단이 필요한 증상입니다. 질문은 "Claude Code에서 일반적으로 무슨 문제가 생기나?"가 아니라, "지금 내가 어느 가지에 있고, 그 가지에서 가장 작은 올바른 조치가 무엇인가?"입니다. 첫 단계는 error code 보정입니다. 실제 로그가 429라면 이 페이지의 overload playbook을 계속 따르면 안 됩니다. 진짜 529일 때만 과부하 경로를 유지하세요.
| 지금 보이는 상황 | 가장 가능성이 높은 owner | 가장 안전한 첫 조치 | 같은 path에서 무엇을 확인할지 | 언제 에스컬레이션할지 |
|---|---|---|---|---|
실제로는 429 또는 usage warning이고 529가 아님 | rate-limit / usage branch | 529 절차를 멈추고 usage / limit 진단으로 전환 | 정확한 code와 문제의 핵심이 plan인지 API usage인지 확인 | 정리 후에도 실제 code가 529인 경우 |
| Claude Status가 빨갛거나 새 incident가 진행 중 | Anthropic 측 과부하 또는 서비스 저하 | 로컬 설정 변경을 멈추고 복구를 기다림 | incident가 끝난 뒤 같은 path를 다시 실행 | status가 녹색으로 돌아온 뒤에도 같은 path가 529 |
| status는 녹색인데 같은 path가 계속 529 | 일시적이거나 부분적인 과부하 | 같은 path에 대해 짧은 bounded retry를 한 번 수행 | 다른 변수를 바꾸지 않고 그 path 자체가 회복됐는지 확인 | 짧은 retry를 반복해도 여전히 529 |
| Claude Code가 API key, proxy, 다른 provider route를 쓰는 것 같음 | ANTHROPIC_API_KEY, proxy path, 잘못 짚은 auth owner | /status, env variables, route config를 먼저 확인 | 원래 의도한 route에서 같은 요청을 비교 | intended route로 돌려도 현재 evidence와 함께 529가 남음 |
이 표가 이 글의 핵심입니다. 뒤의 본문은 각 줄을 좀 더 확실하게 판단할 수 있게 도와주는 역할만 합니다. 시간을 가장 많이 잃는 이유는 해결책이 없어서가 아니라, 처음에 잘못된 가지로 들어가서 신호가 약한 행동을 많이 하기 때문입니다.
529는 무엇이고, 왜 429가 아닌가
Anthropic의 API error docs는 429를 rate_limit_error, 529를 overloaded_error로 구분합니다. 둘 다 "더 진행되지 않는다"는 체감은 비슷하지만, 첫 조치는 다릅니다.
code가 정말 529라면 먼저 service saturation으로 보는 편이 안전합니다. 그래서 status 확인, 같은 route 유지, 짧은 retry가 먼저이고, quota나 billing 논의는 그다음입니다. 반대로 429라면 이야기는 overload가 아니라 rate limit 또는 usage interpretation 쪽입니다. 그때는 Claude Code token usage guide나 더 좁은 Claude Code rate limit reached 가이드가 맞습니다.
중요한 것은 "막혔다"는 느낌이 아니라 "정확한 code"입니다. 529는 자동으로 개인 한도 소진을 뜻하지 않고, 429는 서비스가 바빠 보인다고 해서 overload가 되지 않습니다.
Claude Status가 지금 incident를 보여주는 경우
status를 제일 먼저 보는 이유는 불필요한 로컬 디버깅을 통째로 줄일 수 있기 때문입니다. Claude Status가 Claude API, Claude Code, login 주변에서 빨간색이라면 가장 안전한 첫 조치는 대개 기다리는 것입니다.
오류가 내 터미널에서 나왔으니 문제도 내 설정에 있다고 느끼기 쉽습니다. 그래도 incident가 진행 중이라면 reinstall, route 변경, login 재시도, credential 교체를 계속하는 것은 신호보다 잡음을 더 많이 만듭니다.
이 가지에서 남길 것은 많지 않습니다. 정확한 error text, 시각, 그리고 가능하다면 request_id면 충분합니다. Anthropic은 docs에서 error response에 request_id가 포함된다고 설명합니다. incident가 끝나면 같은 path를 다시 시도하세요. same-path verification이 있어야 incident가 전부였는지 아닌지 알 수 있습니다.
하지만 이 가지를 만능 설명으로 만들면 안 됩니다. status가 다시 녹색이 되면 질문은 "지금 전체가 다운인가?"에서 "왜 이 path만 아직도 안 돌아왔나?"로 바뀝니다.
status는 녹색인데 같은 path가 계속 529를 반환하는 경우
녹색 status는 로컬 변경을 무작정 늘리라는 허가가 아닙니다. live-incident branch가 약해졌다는 뜻일 뿐, overload diagnosis가 끝났다는 뜻은 아닙니다.
가장 답답한 가지가 바로 여기입니다. 공식 code는 과부하를 가리키고, public status는 정상이지만, 터미널은 계속 실패합니다. 이런 상황에서는 #3558나 #3572 같은 official-repo issue가 도움이 됩니다. 하나의 만능 root cause를 증명하는 것은 아니지만, "녹색 status와 반복되는 529가 함께 나타날 수 있다"는 점은 분명히 보여줍니다.
여기서의 올바른 첫 조치는 bounded same-path retry입니다. 잠깐 기다린 뒤 같은 action을 같은 route로 한 번 다시 실행하세요. model, billing path, auth route, session state를 동시에 바꾸지 마세요. 그렇게 하면 원래 path가 스스로 회복된 건지, 아니면 다른 가지로 도망친 건지 알 수 없게 됩니다.
이 가지에서 흔한 실수는 upgrade, reinstall, 대규모 config 변경처럼 "큰 수리"를 너무 빨리 하는 것입니다. 먼저 답해야 하는 질문은 더 작습니다. 같은 path가 짧은 대기 뒤에 돌아왔는가. 아니면 support로 넘길 만큼 재현 가능한 failure인가.
usage 또는 API key route에 들어가 있는 것 같을 때
529 진단이 자꾸 빗나가는 큰 이유 중 하나는 사용자가 Claude Code가 자신이 생각하는 auth route를 쓰고 있다고 믿기 쉽기 때문입니다. Anthropic의 Pro / Max help는 ANTHROPIC_API_KEY가 설정되어 있으면 Claude Code가 subscription auth 대신 그 key를 쓴다고 설명합니다. 이 한 줄만으로도 많은 오진을 설명할 수 있습니다.
subscription path를 보고 있다고 생각해도 shell이 ANTHROPIC_API_KEY를 export하고 있으면 전제가 깨집니다. 먼저 /status와 환경을 확인해 active route를 확정하세요. route를 잘못 짚은 상태에서 quota나 service availability를 논하면 그 뒤의 판단이 다 흔들립니다.
proxy, wrapper, alternate provider route도 같습니다. 첫 조치는 provider shopping이 아닙니다. intended route로 돌아가고, 낡은 가정을 치우고, 같은 요청을 그 route에서 다시 비교하는 것입니다. 의도치 않은 API key를 제거하거나 intended auth path로 돌아간 뒤 529가 사라지면 진짜 가지는 route mismatch였습니다. intended route에서도 529가 남는다면 overload 해석이 여전히 더 강합니다.
이 절도 넓어지면 안 됩니다. 실제 문제의 중심이 usage exhaustion이나 shared-plan drain이라면 Claude Code usage limits 진단 가이드로 넘기는 편이 빠릅니다. 실제 증상이 500이라면 Claude Code API Error 500 가이드가 더 맞습니다.
수정 후 확인과 에스컬레이션 경계
529 recovery를 빠르게 만드는 가장 좋은 습관은 "뭔가 달라졌나?"보다 "이 path가 이 한 번의 조치 뒤에 돌아왔나?"를 보는 것입니다. same-path verification은 blind retry, 무의식적인 branch switching, 약한 support report를 동시에 줄여 줍니다.
에스컬레이션 전에 같은 failing path에서 최소한 이것만 모으세요.
529또는overloaded_error를 포함한 정확한 error textrequest_id또는request-id- 그 시점의 Claude Status 상태
- bounded retry 후에도 실패했는지, intended route로 돌려도 실패했는지
- 최소 reproduction steps 또는 relevant
/statusoutput
이 목록은 짧을수록 좋습니다. support에 필요한 것은 긴 시도 기록보다 재현 가능한 깔끔한 이야기이기 때문입니다. "녹색 status, 같은 path가 짧은 retry 후에도 529, request_id 첨부"는 좋은 보고입니다. "이것저것 바꿨는데 아직 안 됨"은 약한 보고입니다.
에스컬레이션 경계도 단순합니다. status checked, route checked, bounded retry done, 그런데도 같은 path가 여전히 529라면 즉흥적인 추가 수정보다 clean handoff가 더 가치 있습니다.
Frequently Asked Questions
Claude Code API Error: 529와 429 rate_limit_error는 같은가요?
아닙니다. Anthropic의 API error docs는 둘을 다른 error type으로 정의합니다. 429는 rate limit, 529는 overload입니다.
Claude Status가 녹색인데 왜 아직도 529가 보이나요?
녹색 public status는 live-incident branch만 약하게 만들 뿐입니다. 내 Claude Code path가 이미 회복되었다는 보장은 아닙니다. 다음 조치는 same-path retry 또는 route check입니다.
529가 나오면 바로 plan을 바꿔야 하나요?
첫 조치로는 권하지 않습니다. 529는 먼저 overload를 뜻합니다. code와 active route를 확인한 뒤에 plan이나 billing을 생각하세요.
subscription path라고 생각했는데 동작이 이상하면 무엇을 봐야 하나요?
ANTHROPIC_API_KEY가 설정되어 있는지 확인하고, /status와 environment variables로 active route를 확정하세요. Anthropic은 이 key가 subscription auth를 덮어쓴다고 설명합니다.
support에는 무엇을 보내야 하나요?
정확한 error text, request_id, status 상태, 테스트한 path, 최소 reproduction steps를 보내세요. 목표는 긴 설명이 아니라 모호성을 줄이는 것입니다.
Working Rule
Claude Code의 API Error: 529는 "내 한도가 찼나?"보다 "과부하를 어떻게 branch-first로 복구할까?"로 다루는 편이 안전합니다. 먼저 Status, 그다음 path를 고정하고 bounded move를 한 번만 수행한 뒤, 같은 path로 검증하고, 그래도 실패하면 evidence와 함께 에스컬레이션하세요.