Claude API 오류 529 overloaded_error — 의미와 대응 방법

529는 코드가 일으킨 것이 아닌 Claude 오류입니다. Anthropic 자체가 과부하 상태인 것입니다. 고칠 수는 없지만 잘 흡수할 수는 있습니다. 즉, 인내심 있는 재시도, 대체 모델, 그리고 즉시 반복 시도로 상황을 절대 증폭하지 않는 것이 중요합니다.

오류

resposta (HTTP 529)

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

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

원인	해결 방법
공급업체 포화 상태(출시일, 지역 장애)	지터를 포함한 지수 백오프를 사용하세요. 배포를 다시 실행하기보다 공급업체 상태 페이지를 확인하세요.
부분 장애 중 트래픽 급증이 발생했습니다	작업을 배치로 분산하세요. 보통 10분 정도 기다리면 해결됩니다.
즉시 반복 재시도	즉시 다시 시도하면 부하가 배가되고 장애가 모두에게, 물론 당신에게도 더 오래 지속됩니다.

올바른 방식으로 재시도하세요

529를 retry-after 헤더가 없는 429처럼 처리하세요. 약 2초부터 시작하는 지수 백오프에 지터를 추가하고, 상한은 30–60초로 두며 약 5회 시도 후 포기하고 작업을 큐에 넣습니다. 429를 처리하는 동일한 코드 분기를 529에도 사용할 수 있습니다.

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

중단하는 대신 모델을 바꾸세요

지연 시간에 민감한 경로에는 대체 모델을 지정하세요. 같은 제품군(Sonnet → Haiku)에서는 동작이 비슷하게 유지되고, 공급업체 간(Claude → GPT) 전환이면 전체 장애를 견딜 수 있습니다. OpenAI 호환 엔드포인트에서는 문자열 하나만 바꾸면 됩니다.

failover.py

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

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

529를 429나 402와 혼동하지 마세요

429는 한도를 초과했다는 뜻이며 서버는 정상입니다. 529는 서버가 과부하라는 뜻이며 사용자의 할당량은 정상입니다. 402는 잔액 부족입니다. 로그에서는 세 오류가 비슷해 보이지만 해결 방법은 완전히 다릅니다. 재시도해야 하는 것은 429와 529뿐입니다.

Kunavo를 통해 호출하는 경우

Kunavo에서는 동일한 멀티모델 카탈로그가 하나의 키와 하나의 지갑 뒤에 있으므로, 위 예시처럼 공급업체 간 장애 조치를 하려면 모델 이름만 바꾸면 됩니다 — 두 번째 계정이나 가입이 필요하지 않습니다. 실패한 요청에는 요금이 부과되지 않습니다. 용량과 가격은 별개의 문제입니다. 두 번째 문제에 대한 토큰별 요금은 Claude API 가격 가이드.

자주 묻는 질문

529 오류는 제 책임인가요?

아니요. 공급업체 측의 용량 문제입니다. 사용자의 책임은 백오프와 지터로 문제를 증폭하지 않는 것, 그리고 장애가 지연 시간 예산보다 오래 지속될 때 이동할 곳을 마련해 두는 것뿐입니다.

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

429는 사용자가 한도를 초과했다는 뜻이고, 529는 서버가 과부하라는 뜻입니다. 둘 다 재시도할 수 있지만 retry-after 안내가 함께 오는 경우는 대개 429입니다.

529가 발생한 요청에도 요금이 부과되나요?

부과되지 않아야 합니다 — 요청이 토큰을 생성하지 않았기 때문입니다. Kunavo에서는 실패한 요청이 잔액에서 차감되지 않습니다.