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 — 의미와 올바른 대처법

오류