Claude 529 오류(overloaded_error)의 원인과 처리 방법

529는 프로그램 때문에 발생하지 않는 유일한 Claude 오류입니다. 과부하 상태인 곳은 Anthropic 측입니다. 이를 고칠 수는 없고, 지수 백오프를 적용한 인내심 있는 재시기, 지연 시간에 민감한 경로를 위한 대체 모델 준비, 그리고 즉시 재시도를 반복해 장애를 키우지 않는 방식으로 대응해야 합니다.

오류

回應（HTTP 529）

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

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

원인	해결 방법
공급업체 측 과부하(신규 모델 출시일, 지역 장애)입니다. 모든 고객이 동시에 겪습니다.	지터를 포함한 백오프 대기를 사용하고, 자체 애플리케이션을 다시 배포하지 말고 Anthropic 상태 페이지를 확인하세요.
자체 트래픽 피크가 이미 빠듯한 용량과 겹친 경우입니다.	배치 작업을 시간상 분산하세요. 보통 10분 정도 지연하면 해결됩니다.
429와 혼동하는 경우입니다. 로그에서는 둘이 비슷해 보이지만 원인은 완전히 다릅니다.	429는 자체 한도를 초과한 경우입니다(서버는 정상). 529는 서버 자체가 과부하인 경우입니다(할당량에는 문제가 없음). Retry-After 안내가 함께 제공되는 것은 429뿐입니다.
대체 경로를 정의하지 않아 공급업체 문제가 최종 사용자에게 그대로 전달되는 경우입니다.	먼저 대체 순서를 정하세요. 같은 계열(Sonnet → Haiku)은 동작이 더 비슷하고, 공급업체 간 전환(Claude → GPT)은 한 업체 전체에 장애가 발생한 상황을 견딜 수 있습니다.

재시도가 장애를 키우지 않게 하기

529를 "Retry-After가 없는 429"로 처리하세요. 약 2초부터 시작하는 지수 백오프에 지터를 추가하고, 상한은 30〜60초로 두며, 약 5회 후에는 포기하고 작업을 큐에 넣습니다. 실제로 효과를 내는 부분은 지터입니다. 지터가 없으면 모든 클라이언트가 같은 순간에 돌아와, 빠져나가려던 혼잡을 그대로 연장합니다.

중단하지 말고 우회하세요

지연 시간에 민감한 경로에는 대체 체인을 미리 정의해야 합니다. OpenAI 호환 엔드포인트에서는 문자열 하나만 바꾸면 됩니다. 별도의 SDK를 연결하거나 계정을 추가로 만들 필요가 없습니다.

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          # 過載 —— 試下一個
    raise last

마지막에야 자체 프로그램을 의심하기

특정 요청만 529가 발생하고 같은 시간에 다른 호출은 정상이라면 전면 장애가 아닙니다. 해당 경로가 비정상적으로 큰 프롬프트를 보내는지, 또는 매우 짧은 루프에서 연속으로 전송하는지 확인하세요. 반대로 모든 호출이 동시에 529가 되었다가 잠시 후 저절로 정상화된다면 원인은 용량입니다. 수정해야 할 것은 재시도와 대체 경로이지 리팩터링이 아닙니다.

Kunavo를 통해 호출하는 경우

Kunavo는 Claude를 둘 이상의 업스트림 경로로 분산하며, 다중 모델 카탈로그를 통해 공급업체 간 대체를 "하나의 키, 하나의 잔액, 모델 이름만 변경"으로 만듭니다. 위 코드는 두 번째 계정이 필요하지 않습니다. 529가 사용자에게 전달되더라도 언제나 과금되지 않습니다. 용량과 가격은 별개의 문제입니다. 후자에 대해서는 각 모델의 단가가 Claude API 비용표.

자주 묻는 질문

529는 내 문제인가요?

아닙니다. 공급업체 측 용량 문제입니다. 사용자 측 책임은 두 가지뿐입니다. 장애를 키우지 않는 것(백오프와 지터), 그리고 장애가 지연 시간 예산을 초과할 때 우회할 곳을 마련하는 것입니다.

529와 429는 어떻게 다른가요?

429는 자체 한도를 초과한 상태이며 서버는 정상입니다. 529는 서버 자체가 과부하인 상태이며 사용자의 할당량에는 문제가 없습니다. 둘 다 재시도할 수 있지만 Retry-After 안내가 함께 제공되는 것은 429뿐입니다.

529는 보통 얼마나 지속되나요?

예측할 수 없고 보장할 수도 없습니다. 따라서 정답은 프로그램에 대기 시간을 고정하는 것이 아니라 "상한이 있는 백오프와 큐"입니다. 해당 경로에 지연 시간 예산이 있다면 기다리는 대신 대체 경로가 처리해야 합니다.

529로 실패한 호출도 과금되나요?

Kunavo를 통한 요청은 과금되지 않습니다. 오류로 종료된 요청은 과금 대상에 포함되지 않습니다. 공급업체와 직접 계약한 경우에는 각 업체의 과금 규칙에 따릅니다.

Claude API 529 overloaded_error — 이 오류의 의미와 극복 방법

오류