문제 해결 · 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 error
  • claude code 529 keeps happening

자주 묻는 질문

529는 429와 다른가요?+
네. 429는 당신의 처리량 한도이고, 529는 업스트림 용량입니다. 백오프는 둘 다에 도움이 되지만, 사용량을 줄여서 해소되는 것은 429뿐입니다.
제 프롬프트 때문에 529가 났나요?+
아니요. Overloaded는 서비스 쪽 상태입니다. 용량이 회복되면 동일한 요청이 보통 성공합니다.
529가 보이면 모델을 바꿔야 하나요?+
지연에 민감한 작업이라면 다른 GPT 또는 Gemini 모델로 잠시 바꾸는 것이 도움이 됩니다. 용량은 모델별로 따로 계산되기 때문입니다. 그 밖의 경우에는 기다리면 충분합니다.

잘못된 설정에 시간 낭비하지 마세요

apiToken.sale은 OpenAI 호환, Messages(Anthropic 형식), 네이티브 Gemini 엔드포인트로 GPT와 Gemini 모델을 제공합니다 — 표준 SDK, 하나의 키, 하나의 선불 잔액. 도구의 base URL만 지정하면 이 페이지의 설정이 적힌 그대로 작동합니다.