Claude API 오류 529 overloaded_error — 원인과 대응 방법

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

529를 Retry-After가 없는 429처럼 처리하세요. 약 2초부터 지수 백오프를 시작하고 지터를 추가하며, 30~60초에서 상한을 두고, 약 5회 시도 후 포기한 다음 작업을 큐에 넣으세요. 중요한 것은 지터입니다. 지터가 없으면 모든 클라이언트가 동시에 재시도해 벗어나려는 바로 그 포화를 오히려 연장합니다.

실패하는 대신 전환하기

지연 시간에 민감한 경로에는 대체 체인을 정의하세요. OpenAI 호환 엔드포인트에서는 모델 이름 문자열 하나만 바꾸면 됩니다 — 두 번째 SDK도, 두 번째 계정도 필요하지 않습니다:

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          # saturado — probar el siguiente nivel
    raise last

그 다음에야 코드를 살펴보기

다른 호출은 동시에 정상인데 특정 요청 유형에서만 529가 나타난다면 일반적인 장애가 아닙니다. 해당 경로가 비정상적으로 큰 프롬프트를 보내거나 닫힌 루프에서 반복 실행되는지 확인하세요. 반대로 모든 호출에 갑자기 영향을 주었다가 저절로 사라진다면 용량 문제였던 것입니다 — 이 경우 필요한 것은 리팩터링이 아니라 재시도와 대체 경로입니다.

529는 제 책임인가요?

아닙니다. 제공업체 측 용량 문제입니다. 여러분의 책임은 백오프와 지터로 장애를 키우지 않고, 장애가 지연 시간 예산을 초과할 때 사용할 대체 경로를 마련하는 것뿐입니다.

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

429는 한도를 초과했지만 서버는 정상이라는 뜻입니다. 529는 서버 자체가 포화되었지만 여러분의 할당량은 정상이라는 뜻입니다. 둘 다 재시도할 수 있지만 Retry-After 힌트가 제공되는 것은 429뿐입니다.

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

예측하거나 보장할 수 없습니다 — 따라서 올바른 대응은 상한이 있는 백오프와 큐이며, 코드에 고정된 대기 시간을 넣는 것이 아닙니다. 경로에 지연 시간 예산이 있다면 대기하는 대신 대체 경로로 전환하세요.

529로 끝난 호출에도 요금이 부과되나요?

Kunavo를 통한 요청은 그렇지 않습니다. 오류로 끝난 요청에는 요금이 부과되지 않습니다. 직접 계약을 맺은 경우에는 해당 제공업체의 청구 규칙에 따라 달라집니다.