문제 해결 · Claude Code
Claude Code API Error 529 Overloaded의 의미
선택한 GPT 또는 Gemini 모델의 업스트림 용량이 포화되면 Claude Code는 API Error: 529 Overloaded를 출력합니다. 요청 탓이 아닌 이유, 몰려서 발생하는 이유, 실제로 도움이 되는 방법.
표시되는 내용
API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}발생 원인
- 선택한 GPT 또는 Gemini 모델의 업스트림 용량이 일시적으로 포화되었습니다. 엔드포인트는 이를 Claude Code가 이미 재시도하는 상태인 529 overloaded_error로 알립니다. 이는 그 순간의 서비스 상태를 나타낼 뿐 요청 문제가 아닙니다 — 요청 내용에는 원인이 없습니다.
- 장애 중이나 피크 시간대에 몰려서 발생합니다: 같은 요청이 보통 몇 분 뒤 아무것도 바꾸지 않아도 성공합니다.
해결 방법
- Claude Code가 재시도하게 두세요 — 자동으로 백오프합니다. 실행이 계속 중단된다면 같은 분에 반복해서 두드리지 말고 몇 분 기다리세요.
- 장시간 무인 실행에서는 기계적인 단계에 더 가벼운 모델을 고르세요: 대체로 경합이 적어 용량이 출렁여도 실행이 버팁니다.
- 529가 오래 지속되면 ANTHROPIC_MODEL을 다른 GPT 또는 Gemini 모델로 바꾸세요 — 설정이 원인인 경우는 거의 없습니다.
관련 검색어
claude code overloaded errorclaude code 529 keeps happening
자주 묻는 질문
529는 429와 다른가요?+
네. 429는 당신의 처리량 한도이고, 529는 업스트림 용량입니다. 백오프는 둘 다에 도움이 되지만, 사용량을 줄여서 해소되는 것은 429뿐입니다.
제 프롬프트 때문에 529가 났나요?+
아니요. Overloaded는 서비스 쪽 상태입니다. 용량이 회복되면 동일한 요청이 보통 성공합니다.
529가 보이면 모델을 바꿔야 하나요?+
지연에 민감한 작업이라면 다른 GPT 또는 Gemini 모델로 잠시 바꾸는 것이 도움이 됩니다. 용량은 모델별로 따로 계산되기 때문입니다. 그 밖의 경우에는 기다리면 충분합니다.