Claude API 529 overloaded_error — 무엇이며 어떻게 대응할까

529는 코드가 원인을 제공하지 않은 유일한 Claude 오류입니다. Anthropic 자체가 과부하 상태인 것입니다. 이를 고칠 수는 없고, 우아하게 흡수할 수만 있습니다. 즉, 인내심 있는 재시도, 대체 모델, 그리고 즉시 재시도 폭주로 장애를 증폭시키지 않는 것이 필요합니다.

오류

response (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
프로바이더 측 포화 상태(출시일, 지역 장애)	지터를 포함한 백오프를 사용하고, 앱을 재배포하는 대신 프로바이더 상태 페이지를 확인하세요.
소프트 장애 중에 버스트 요청이 도착한 경우	배치 작업을 분산하세요. 보통 10분 지연이면 해결됩니다.

모범적인 방식으로 재시도하기

529를 retry-after가 없는 429로 처리하세요. 약 2초부터 시작하는 지수 백오프, 지터, 30~60초 상한을 적용하고, 약 5회 시도 후 포기하여 작업을 큐에 넣으세요. 429 가이드의 백오프 스니펫은 동일한 분기에서 529도 처리합니다.

실패를 줄이는 대신 장애 조치하기

지연 시간에 민감한 경로에는 대체 경로를 정의하세요. 같은 계열(Sonnet → Haiku)은 동작을 비슷하게 유지하고, 프로바이더 간 전환(Claude → GPT)은 전체 프로바이더 장애에도 대응합니다. OpenAI 호환 엔드포인트에서는 문자열 하나만 바꾸면 됩니다.

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # saturated — try the next tier
    raise last

Kunavo를 통해 호출하는 경우

Kunavo는 Claude를 둘 이상의 업스트림 경로로 라우팅하며, 다중 모델 카탈로그를 통해 동일한 키와 지갑에서 프로바이더 간 장애 조치를 모델 문자열 변경만으로 수행할 수 있습니다. 위의 장애 조치 패턴에 두 번째 계정은 필요하지 않습니다. 여러분에게 도달한 529에는 여전히 요금이 부과되지 않습니다. 용량과 가격은 별개의 문제입니다. 후자의 경우 모델별 요금은 다음에 나와 있습니다. Anthropic Claude API 가격표.

자주 묻는 질문

529는 내 잘못인가요?

아닙니다. 프로바이더 측 용량 문제입니다. 여러분의 책임은 장애를 증폭시키지 않는 것(백오프, 지터)과 장애가 지연 시간 예산을 초과할 경우 전환할 대상을 마련하는 것뿐입니다.

529와 429의 차이는 무엇인가요?

429는 한도를 초과했다는 뜻입니다(서버는 정상). 529는 서버 자체가 과부하라는 뜻입니다(여러분의 할당량은 정상). 둘 다 재시도할 수 있지만 retry-after 힌트가 제공되는 것은 429뿐입니다.