문제 해결 · Claude Code

Claude Code API Error 529 Overloaded 의미와 대처 방법

Claude Code는 업스트림 용량이 포화되면 API Error: 529 Overloaded를 출력합니다. 왜 당신의 요청 탓이 아닌지, 왜 몰려서 발생하는지, 실제로 도움이 되는 것은 무엇인지 설명합니다.

표시되는 내용

API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

발생 원인

  • 업스트림 용량이 일시적으로 포화되었습니다. 529는 그 순간의 서비스 상태를 나타내는 것이지 당신의 요청을 나타내는 것이 아닙니다 — 페이로드의 어떤 것도 원인이 아닙니다.
  • 장애나 피크 시간대에 몰려서 발생합니다: 같은 요청이 보통 몇 분 뒤 아무 변경 없이 성공합니다.

해결 방법

  • Claude Code가 재시도하도록 두세요 — 자동으로 백오프합니다. 실행이 계속 죽는다면 같은 1분을 두드리지 말고 몇 분 기다리세요.
  • 무인 장기 실행에는 기계적인 단계에 더 작은 모델을 쓰는 편이 좋습니다: 일반적으로 경합이 덜해 용량 저하를 견딥니다.
  • 529가 오래 지속되면 설정을 바꾸기 전에 프로바이더의 상태 페이지를 확인하세요 — 당신의 설정이 원인인 경우는 거의 없습니다.

관련 검색어

  • claude code overloaded error
  • claude code 529 keeps happening

자주 묻는 질문

529는 429와 다른가요?+
네. 429는 당신 자신의 처리량 한도이고, 529는 업스트림 용량입니다. 백오프는 둘 다에 도움이 되지만, 사용량을 줄이는 것은 429에만 효과가 있습니다.
제 프롬프트가 529를 일으켰나요?+
아니요. Overloaded는 서비스 측 상태입니다. 동일한 요청이 보통 용량이 회복되면 성공합니다.
529가 보이면 모델을 바꿔야 하나요?+
지연에 민감한 작업이라면 일시적으로 더 작은 모델을 쓰는 것이 도움이 됩니다 — 경합이 덜하기 때문입니다. 그 외에는 기다리는 것으로 충분합니다.

Claude Code 오류 전체 · Claude API 오류 코드 · 설정 가이드

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

apiToken.sale은 표준 Anthropic API를 제공합니다 — 같은 모델, 같은 SDK, 하나의 선불 잔액. 도구의 base URL만 지정하면 이 페이지의 설정이 적힌 그대로 작동합니다.

키 받기API 문서