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          # saturé — passer au palier suivant
    raise last

그다음에야 자체 코드를 확인하세요

529가 한 가지 요청 유형에서만 발생하고 같은 시간에 다른 호출은 성공한다면 전체 장애가 아닙니다. 해당 경로가 비정상적으로 큰 프롬프트를 보내거나 좁은 루프에서 반복 호출하는지 확인하세요. 반대로 모든 호출에서 동시에 발생했다가 저절로 사라진다면 용량 문제였던 것입니다. 이 경우 작업은 재시도와 폴백으로 처리해야 하며 리팩터링이 필요하지 않습니다.

529는 제 잘못인가요?

아니요. 제공업체 측 용량 문제입니다. 사용자의 책임은 장애를 악화시키지 않는 것(백오프, 지터)과 장애가 지연 시간 예산보다 오래 지속될 때 사용할 대체 경로를 마련하는 것뿐입니다.

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

429는 제한을 초과했지만 서버는 정상이라는 의미입니다. 529는 서버 자체가 과부하 상태지만 사용자의 할당량은 정상이라는 의미입니다. 둘 다 재시도할 수 있지만 Retry-After 힌트를 제공하는 것은 429뿐입니다.

529 상태는 얼마나 지속되나요?

예측할 수 없고 보장할 수도 없습니다. 따라서 올바른 대응은 코드에 고정된 대기 시간을 넣는 것이 아니라 상한이 있는 백오프와 큐를 사용하는 것입니다. 경로에 지연 시간 예산이 있다면 기다리는 대신 폴백이 이어받도록 하세요.

529 호출에도 요금이 청구되나요?

Kunavo에서는 청구되지 않습니다. 오류로 끝난 요청은 청구되지 않습니다. 직접 계약을 맺은 경우에는 해당 제공업체의 청구 규정에 따라 달라집니다.