Claude API가 HTTP 529와 overloaded_error를 반환하면 먼저 Anthropic 쪽 용량 분기라고 보아야 합니다. 내 계정이 429 rate limit에 걸렸다고 바로 결론 내리지 마세요. 먼저 Claude Status를 확인하고, 즉시 반복되는 retry loop를 멈추고, 병렬 호출을 낮춘 뒤, 상한이 있는 exponential backoff와 jitter로 다시 시도합니다. 검증 중에는 endpoint, model, workspace, key, proxy, client library를 동시에 바꾸지 말고 request_id와 시간을 남기세요.
| 응답 신호 | 가능성이 큰 소유자 | 첫 조치 | 멈출 기준 |
|---|---|---|---|
HTTP 529 + overloaded_error | Anthropic 전체 용량 | 상태 확인, 느린 retry, 새 작업 queue | retry 예산 소진 후 증거 보존 |
HTTP 429 + rate_limit_error | 조직 또는 workspace limit | rate-limit header 확인 | reset 또는 limit 변화까지 대기 |
| HTTP 500 또는 504 | 서버 오류 또는 처리 timeout | 상태 확인, 작은 동일 경로 요청 | 지속 재현 시 request evidence로 escalation |
| Claude Code repeated 529 | Claude Code가 이미 자동 retry 수행 | 상태 확인, 대기, 필요 시 model 전환 | quota 소진으로 단정 금지 |
수리 규칙은 좁습니다. 529는 retry할 수 있지만 느리게, 상한을 두고, 동시에 압력을 낮춰야 합니다. 즉시 loop, key 교체, 429용 quota playbook은 진단을 흐리게 만듭니다.
529는 용량 분기이지 quota 분기가 아니다
Anthropic API error reference는 529를 조직 rate limit과 분리합니다. 429는 rate limit, 500은 내부 API error, 504는 timeout, 529는 API가 일시적으로 overloaded 된 상태입니다. 그래서 첫 조치도 다릅니다. 429는 headers와 reset window를 읽어야 하고, 529는 service state를 확인한 뒤 같은 request path에서 제한된 retry와 queue를 사용해야 합니다.
status page도 단순히 정상 또는 장애로만 보지 않습니다. 2026-04-30T13:42:00+08:00 기준 Statuspage API는 Claude API component를 operational로 보여주었지만, 같은 날 이른 시간과 전날에는 관련 incident가 있었습니다. 용량 문제에서는 전체 component가 복구되어도 특정 model, route, wrapper, 또는 짧은 window에서 529가 남을 수 있습니다.
증상을 너무 빨리 지우지 마세요. response body, HTTP status, error type, request_id, model, endpoint, workspace, provider route, local timestamp를 저장합니다. 나중에 성공하더라도 그 기록은 대기, concurrency 감소, payload 축소, route 변경 중 무엇이 효과였는지 알려줍니다.
처음 5분은 request path를 고정한다
먼저 evidence를 모읍니다. body와 headers, request id, model, endpoint, workspace, provider route, input size, concurrency, timezone 포함 timestamp를 기록합니다. Claude Status를 열어 Claude API, Claude Code, model-specific incident를 확인합니다. Zapier, Make, custom proxy, hosted agent가 중간에 있다면 그 layer를 따로 적어야 합니다.
그 다음 같은 path로 작은 request를 보냅니다. API key, organization, model, endpoint, client library는 그대로 두고 prompt와 output cap만 줄입니다. 작은 request가 성공하고 production burst가 실패한다면 traffic shaping이 수리 지점입니다. 작은 request도 529를 반환한다면 capacity 또는 provider route pressure 가능성이 커집니다.
stop rule이 필요합니다. foreground request는 보통 세 번에서 다섯 번의 backoff면 충분합니다. batch job은 더 오래 기다릴 수 있지만 worker를 붙잡지 말고 durable queue로 돌려보내야 합니다. 예산이 끝나면 temporary capacity state를 반환하고 job과 evidence를 남깁니다.
retry는 느리게, 하드 캡을 두고
529가 retryable이라는 뜻은 capacity가 돌아오면 같은 요청이 성공할 수 있다는 뜻입니다. 즉시 많이 보내면 성공한다는 뜻이 아닙니다. retry policy는 load를 분산하고 worker를 보호하며 원인 분리를 유지해야 합니다.
hljs tsfunction classifyClaude(status: number, type?: string) {
if (status === 529 || type === "overloaded_error") return "slow_retry";
if (status === 429 || type === "rate_limit_error") return "wait_for_limit";
if (status === 500 || status === 504) return "server_or_timeout";
return "do_not_retry_blindly";
}
핵심은 ceiling입니다. UI request는 몇 번 시도한 뒤 temporary failure를 반환할 수 있습니다. batch worker는 next retry time과 attempt count를 저장하고 queue로 돌아갈 수 있습니다. streaming UI는 model path가 일시적으로 overloaded 됐다고 알려야 하며, 설명 없이 멈춰 있으면 안 됩니다.
529와 429를 같은 repair branch에 넣지 마세요. rate limit docs는 429가 retry-after와 rate-limit headers를 가질 수 있다고 설명합니다. 529에서는 내 account bucket의 reset이 주 신호가 아니므로 backoff policy와 service state를 기준으로 조절합니다.
진단을 잃지 않으면서 압력을 낮춘다
압력 감소는 비교 조건을 보존할 때 의미가 있습니다. worker concurrency를 낮추고, speculative fan-out을 중단하고, 새 작업을 queue에 넣고, context를 줄이고, SDK와 wrapper가 이중으로 aggressive retry를 만들지 않는지 확인합니다. SDK가 이미 transient failure를 retry한다면 외부 wrapper는 더 엄격한 상한을 가져야 합니다.
긴 작업은 synchronous request에 모두 밀어 넣지 마세요. 즉시 응답이 필요 없으면 queue나 batch로 옮기고, 긴 출력은 streaming을 사용해 idle timeout과의 혼동을 줄입니다. 큰 shared context를 반복한다면 prompt caching이 account-side token pressure와 burst behavior에는 도움이 되지만 529가 사라진다는 보장은 아닙니다.
model 전환은 continuity tactic입니다. product contract가 다른 품질을 허용할 때만 적합합니다. 원래 model이 반드시 필요하다면 조용히 바꾸는 대신 기다렸다가 같은 path로 retry하는 편이 낫습니다.
escalation 전에 같은 path로 검증한다
가장 깨끗한 검증은 same-path small-load test입니다. key, organization, workspace, endpoint, model, client library, proxy, network path를 고정하고 작은 request와 낮은 concurrency의 production shape를 비교합니다. 이 조합은 provider pressure, request size, burst pattern, wrapper layer를 구분합니다.
overload log는 일반 로그와 분리하세요. request id, status, error type, model, endpoint, workspace, provider route, attempt, delay, input token estimate, output cap, final disposition을 저장합니다. Anthropic docs는 request id가 support 조사에 도움이 된다고 설명합니다. request ids, timestamps, status snapshot, same-path reproduction이 있는 보고가 terminal screenshot보다 훨씬 강합니다.
지속적이고 넓게 재현될 때 escalation합니다. Zapier, Make, proxy만 실패하고 direct Anthropic call이 성공한다면 중간 layer부터 봅니다. direct small request도 529이고 status가 깨끗하다면 request id와 시간대를 포함해 support로 보냅니다. active incident가 있으면 evidence를 보존하고 queue가 회복을 기다리게 합니다.
Claude Code, gateway, automation platform 분리
Claude Code는 별도의 surface behavior를 갖습니다. error reference는 server errors, overloaded responses, timeouts, temporary throttles, dropped connections가 사용자에게 보이기 전에 자동 retry된다고 설명합니다. terminal에서 repeated 529를 본 시점에는 이미 여러 번 시도한 뒤입니다. 다음 단계는 status, 대기, 필요 시 model switch이지 Console API quota가 끝났다는 결론이 아닙니다.
gateway와 automation 제품은 새 branch를 추가합니다. Zapier, Make, proxy, hosted agent는 error를 replay, delay, transform할 수 있습니다. upstream Anthropic status와 wrapper status를 분리하세요. platform이 generic failure만 보여준다면 원본 HTTP status와 Anthropic error type을 기록하는 logging을 추가해야 합니다.
production에서는 작은 state machine이 안정적입니다. classify error, check service status, retry with cap, reduce pressure, queue deferred work, preserve request evidence. 이 순서가 key rotation, immediate loop, silent model downgrade보다 안전합니다.
Production checklist
| Control | 529에서의 의미 | 구현 |
|---|---|---|
| Error classifier | 529와 429/500/504를 분리 | HTTP status와 error type 확인 |
| Capped jittered retry | retry storm 방지 | foreground와 batch 예산 분리 |
| Concurrency limits | worker 동시 기상 방지 | model, endpoint, route별 cap |
| Durable queue | 사용자 요청 보호 | next retry time과 attempt 저장 |
| Same-path probe | 작은 request 가능성 확인 | key, workspace, model, route 고정 |
| Request id logging | support evidence 확보 | body와 header의 id 저장 |
| Status observation | incident와 local pressure 분리 | checked time과 component 기록 |
복구 후에는 짧은 postmortem도 남겨야 합니다. attempt, delay, concurrency, input size, output cap, status snapshot, final disposition을 같은 event에 저장하세요. 다음에 529가 나타났을 때 담당자는 queue 유지, backoff window 확대, 특정 model concurrency 감소, support evidence 제출 중 무엇을 해야 하는지 빠르게 판단할 수 있습니다. 복잡한 관측 시스템이 없어도 request_id로 조회 가능한 structured log는 최소 요건입니다.
여러 retry layer도 확인해야 합니다. frontend, API gateway, worker, SDK, message queue가 각각 retry하면 세 번의 의도가 수십 번의 요청으로 커집니다. capacity branch에서 가장 위험한 것은 이런 숨은 증폭입니다. retry owner를 한 곳으로 고정하고 다른 layer는 temporary capacity state만 전달하게 하면 부하와 진단이 모두 안정됩니다.
자주 묻는 질문
Claude API 529는 quota를 소모하나요?
먼저 capacity branch로 처리하세요. Claude Code reference는 repeated 529를 usage limit과 분리합니다. direct API에서는 Billing과 Usage도 별도로 확인하되, overloaded_error에 429 repair를 적용하지 마세요.
overloaded_error를 바로 retry해도 되나요?
안 됩니다. backoff, jitter, ceiling이 필요합니다. 즉시 retry는 서비스가 감속을 요구하는 순간에 더 많은 부하를 만듭니다.
model switch가 해결인가요?
작업을 이어가기 위한 방법입니다. 다른 model quality가 허용될 때만 적합하며, 원래 model이 필요한 요청은 기다렸다가 retry해야 합니다.
support에는 무엇을 보내야 하나요?
request ids, timezone 포함 timestamps, model, endpoint, workspace, provider route, status-page state, retry schedule, same-path small request 결과를 보내세요.
