Claude API 요청이 529 overloaded_error를 반환하면 첫 판단은 Anthropic 쪽 용량 과부하입니다. key, billing, 개인 quota, account 상태가 바로 망가졌다고 결론 내리지 마세요. 가장 가까운 함정은 429 rate_limit_error와 섞는 것입니다. 429는 rate limit 또는 quota 분기이고, 529는 capacity 분기입니다.
처음 1분은 작고 순서 있게 움직입니다. Claude Status 결과와 확인 시간을 기록하고, jitter가 들어간 짧은 retry budget으로 재확인합니다. 호출자 쪽 traffic을 제어할 수 있다면 concurrency를 낮추고, 급하지 않은 batch를 멈추고, queue로 압력을 흡수합니다. 그 다음 같은 model, endpoint, auth path, request shape로 다시 확인합니다. 같은 경로가 계속 529를 반환하면 error body와 request_id를 보존하고 에스컬레이션합니다.
상태 페이지는 timestamp signal일 뿐입니다. 이 run에서 2026-04-29 11:02 UTC에 public status API는 all systems operational을 표시했지만, incident feed에는 4월 28일과 4월 29일 UTC의 resolved elevated-error 이벤트가 남아 있었습니다. green status는 분기를 좁히지만 정확한 경로의 회복을 증명하지는 않습니다.
1분 분기표
key, billing, model, provider를 건드리기 전에 exact signal을 먼저 봅니다.
| exact signal | 먼저 볼 분기 | 첫 행동 | 같은 경로 검증 | 중단 또는 에스컬레이션 조건 |
|---|---|---|---|---|
529 또는 overloaded_error | Anthropic capacity overload | live status 확인 후 capped jitter retry | 같은 model, endpoint, auth route, request shape | status, retry budget, 압력 완화 후에도 지속 |
429 또는 rate_limit_error | rate limit 또는 quota | retry-after, limit, credential route 확인 | 허용 window나 route 수정 후 재시도 | headers와 Console이 여전히 limit을 가리킴 |
500 또는 api_error | server error | status 확인, request evidence 저장, 짧은 retry | 짧은 pause 후 같은 request | incident 없이 같은 경로가 반복 실패 |
504 또는 timeout_error | timeout | request 시간을 줄이고 stream 또는 분할 적용 | 한 가지 shape 변경 후 같은 task 검증 | 긴 request가 계속 timeout |
| Claude Code terminal의 반복 529 | Claude Code surface | API 의미 확인 후 terminal 분기 처리 | 같은 session과 route를 cooldown 후 확인 | status와 route check 후에도 지속 |
운영 결론은 간단합니다. 529는 overload first입니다. error가 429, auth error, 명확한 provider limit으로 바뀌지 않았다면 key rotation, plan upgrade, prompt rewrite부터 시작하지 마세요.
Claude API에서 529가 뜻하는 것
Anthropic API error documentation은 HTTP 529를 overloaded_error로 정의합니다. 같은 표에서 429 rate_limit_error, 500 api_error, 504 timeout_error를 별도로 나눕니다. 이 공식 분리가 복구 경계입니다.
핵심 차이는 ownership입니다. 진짜 529는 service가 overloaded 또는 capacity pressure 상태라는 뜻입니다. client가 더 얌전하게 행동해야 하는 것은 맞지만, 첫 해석은 “내 account quota가 끝났다”가 아닙니다. 진짜 429는 request rate, acceleration limit, model limit, account/provider ceiling 쪽입니다. 500은 server error handling과 evidence capture, 504는 duration과 request shape를 봐야 합니다.
나쁜 수정은 모든 blocked request를 하나로 뭉칠 때 생깁니다. 실패했으니 429처럼 느리게 보내고, auth 문제처럼 key를 바꾸고, route 실패처럼 provider를 바꿉니다. 각 행동은 다른 분기에서 쓸 수 있지만 clean 529의 첫 행동은 아닙니다.
request_id는 초기에 보존해야 합니다. Anthropic docs는 error response에 request_id가 포함된다고 설명하고, response header에 request-id가 있을 수도 있습니다. 529가 지속될 때 긴 실험 설명보다 이 identifier가 더 유용합니다.
안전한 복구 루프
좋은 529 handler는 지루해야 합니다. status를 확인하고, 짧게 retry하고, pressure를 낮추고, 같은 경로를 확인한 다음, 멈추거나 에스컬레이션합니다. client를 더 세게 밀어붙이는 것이 아니라 overload를 악화시키지 않으면서 증거를 남기는 것이 목적입니다.
먼저 live status를 확인합니다. 결과와 시간을 UTC 또는 운영 timezone으로 기록합니다. active incident가 있다면 model, endpoint, auth, request size를 동시에 바꾸지 마세요. failing request shape를 유지하고 pause한 뒤 상태가 좋아졌을 때 다시 확인합니다.
status가 green이거나 public incident가 없다면 bounded retry budget을 씁니다. 현실적인 구현에는 exponential backoff, jitter, attempt limit, total elapsed time limit이 들어갑니다. retry는 반복해도 안전한 work에만 적용합니다. read request와 caller-side deduplication이 있는 generation은 side-effecting workflow보다 다루기 쉽습니다.
그 다음 caller pressure를 낮춥니다. concurrency를 낮추고, non-urgent batch job을 멈추고, queue backpressure를 켜고, optional feature를 degraded mode로 전환합니다. 529가 당신 잘못이라는 뜻이 아닙니다. provider overload 중 aggressive retry는 같은 제한된 system에 pressure를 더하기 때문입니다.
마지막으로 same-path verification을 합니다. model, route, auth owner, endpoint, region/proxy path, request shape를 안정적으로 유지합니다. 하나의 변수만 의도적으로 바꾼다면 그 목적을 남깁니다. 다섯 가지를 바꾼 뒤 성공하면 overload가 풀렸는지, route가 달라졌는지, request가 쉬워졌는지 알 수 없습니다.
반복 529를 위한 production control
수동 절차는 사람을 위한 형태이고, service도 같은 discipline을 자동화해야 합니다. 첫째는 retry budget입니다. infinite retry가 아닙니다. attempts, elapsed time, request value가 끝나는 시점을 제한합니다. chat turn, background batch, transactional workflow는 같은 retry policy를 공유하지 않아야 합니다.
jitter도 필요합니다. fixed interval은 traffic을 동기화하고 overloaded API에 가장 나쁜 모양으로 되돌려 보냅니다. jitter는 request를 분산해 recovery spike를 낮춥니다.
반복 529에는 circuit breaker를 둡니다. error rate가 threshold를 넘으면 breaker를 열고, non-urgent work를 queue에 넣고, optional feature를 degrade하고, user-facing message를 명확하게 보여줍니다. breaker를 닫을 때는 작은 same-path probe로 확인하고 batch traffic을 한 번에 되돌리지 않습니다.
pressure reduction과 route change를 분리해야 합니다. pressure reduction은 concurrency 감소, batch window 축소, job defer입니다. route change는 model, endpoint, provider, auth owner를 바꾸는 것입니다. route change는 업무 판단으로 쓸 수 있지만 evidence trail과 product behavior를 바꿉니다.
관측 필드는 단순하면 충분합니다. error type, HTTP status, model, endpoint, auth route, request size class, retry count, final outcome, request_id를 남기세요. 이 정보면 529 spike 중 중요한 질문에 답할 수 있습니다. 같은 경로가 budget 안에서 회복했는가, 아니면 provider overload가 계속되는가.
Claude Code에서 529가 보일 때
먼저 API 레벨의 의미를 적용합니다. 529 overloaded_error는 overload first입니다. 증상이 Claude Code terminal에 있어도 terminal surface가 rule을 추가할 뿐, 529를 billing issue로 바꾸지 않습니다.
Claude Code documentation은 repeated 529를 users across temporary capacity로 설명하고, 메시지가 보이기 전에 Claude Code가 이미 retry했다고 말하며, usage limit 또는 quota wording과 분리합니다. terminal-specific 증상은 Claude Code overloaded error guide로 보내는 편이 맞습니다.
terminal line이 500, 529, 429, temporary limiting, route confusion을 섞는다면 더 넓은 Claude Code 500, 529, rate limit 분기를 사용합니다. terminal은 여러 branch를 한 줄에 압축할 수 있습니다.
API team은 route ownership도 확인해야 합니다. shell environment variable, proxy, provider wrapper 때문에 request가 의도하지 않은 path로 갈 수 있습니다. 하나의 wrapper path에서만 529가 보이면, 같은 request를 의도한 route에서 비교한 뒤 Claude API 전체 문제인지 판단하세요.
에스컬레이션 증거 패킷
에스컬레이션은 작은 recovery path를 끝낸 뒤 시작합니다. current status가 기록되어 있고, retry가 bounded였고, 가능한 pressure reduction을 했고, 같은 경로가 여전히 529를 반환하는 상태입니다.
패킷은 짧게 보냅니다.
- exact HTTP status와 error type, 즉
529 overloaded_error - full error body와 가능한
request_id - model, endpoint, SDK 또는 gateway route, auth owner
- timestamped Claude Status result와 관련 recent incident note
- retry count, backoff window, jitter 사용 여부
- failure 시점의 concurrency 또는 batch pressure
- secret을 제거한 minimal reproduction request shape
- blocked production job, degraded user flow, delayed batch 같은 business impact 한 문장
support에는 모든 local experiment가 필요하지 않습니다. 정확한 branch가 529인지, client가 retry storm을 만들지 않았는지, reasonable control 후 같은 경로가 실패하는지를 확인할 수 있으면 됩니다.
자주 묻는 질문
Claude API 529는 429와 같나요?
아닙니다. Anthropic은 529를 overloaded_error, 429를 rate_limit_error로 정의합니다. 529는 overload first이고, 429는 rate-limit branch입니다.
529는 account나 billing 문제인가요?
첫 해석으로 보지 않습니다. clean 529 overloaded_error는 capacity overload를 가리킵니다. billing, key, quota 조사는 error가 바뀌거나 route가 예상과 다르거나 별도 signal이 있을 때 필요합니다.
Claude Status가 green인데도 529가 계속되면요?
green status는 timestamped signal이지 정확한 path의 회복 증명은 아닙니다. 짧은 same-path retry with jitter, pressure reduction, 같은 model/route/auth/request shape 검증을 하고, 계속 실패하면 request_id로 에스컬레이션합니다.
retry는 몇 번이 안전한가요?
보편적인 숫자보다 budget을 쓰세요. attempt 또는 elapsed time을 제한하고, jitter를 넣고, 반복해도 안전한 work만 retry합니다. user-visible value가 짧은 request는 retry budget도 짧아야 합니다.
529가 나오면 model이나 provider를 바꿔야 하나요?
명시적인 route decision으로는 가능합니다. workload가 다른 route를 허용하면 non-critical flow를 살릴 수 있습니다. 하지만 첫 진단으로 쓰면 original path가 회복했는지 숨깁니다.
Anthropic support에는 무엇을 보내야 하나요?
error body, request_id, model, endpoint 또는 gateway route, auth owner, status timestamp, retry timeline, pressure level, minimal reproduction을 보내세요. secret은 제거하고 branch를 분명히 남깁니다.
운영 규칙
Claude API 529는 overload-first branch입니다. live status를 timestamp와 함께 확인하고, capped jittered budget으로만 retry하며, caller pressure를 낮추고, 같은 경로를 검증합니다. 같은 경로가 계속 529 overloaded_error를 반환할 때 clean evidence와 request_id로 에스컬레이션합니다.