클로드 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 → Gemini) 전면 장애도 버팁니다.

장애를 키우지 않는 재시도로 만든다

529는 “Retry-After 없는 429”처럼 다룹니다. 약 2초에서 시작하는 지수 백오프, 지터 적용, 상한 30~60초, 다섯 번쯤에서 포기하고 작업을 큐에 넣기. 핵심은 지터입니다. 지터가 없으면 모든 클라이언트가 같은 순간에 돌아와, 벗어나려던 그 과부하를 그대로 연장시킵니다.

떨어뜨리지 말고 넘긴다

지연에 민감한 경로에는 폴백 체인을 정의합니다. OpenAI 호환 엔드포인트라면 바꾸는 것은 문자열 하나뿐입니다 — SDK도 계정도 새로 만들 필요가 없습니다:

failover.py

PREFERRED = ["claude-sonnet-4-6", "claude-haiku-4-5", "gemini-2-5-flash"]

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 — 무슨 뜻이고 어떻게 넘길까