Erro 529 overloaded_error da Claude API — o que significa e como contorná-lo

Criar novas tentativas que não agravem a falha

Trate o 529 como um “429 sem Retry-After”. Comece com backoff exponencial de aproximadamente 2 segundos, aplique jitter, limite-o a 30–60 segundos, desista após cerca de cinco tentativas e coloque o trabalho em uma fila. O ponto essencial é o jitter. Sem ele, todos os clientes retornam no mesmo instante e prolongam exatamente a sobrecarga da qual você tentava sair.

Faça failover em vez de falhar

Defina uma cadeia de fallback para caminhos sensíveis à latência. Em um endpoint compatível com OpenAI, basta alterar uma string — não é necessário criar outro SDK nem outra conta:

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

Suspeitar do meu código vem por último

Se o 529 aparece apenas em determinados tipos de solicitação e outras chamadas no mesmo horário passam, não é uma falha geral. Verifique se esse caminho envia um prompt anormalmente grande ou faz chamadas consecutivas em um loop estreito. Por outro lado, se todas as chamadas viram 529 de uma só vez e depois se normalizam sozinhas, a causa é capacidade. Nesse caso, o que você deve ajustar são as novas tentativas e o fallback, não refatorar o código.

O 529 é culpa minha?

Não. É um problema de capacidade do provedor. Suas únicas responsabilidades são duas: não amplificar a falha (backoff e jitter) e ter uma rota alternativa preparada para quando a falha durar mais que sua tolerância à latência.

Qual é a diferença entre 529 e 429?

429 significa que você excedeu seu limite e o servidor está normal. 529 significa que o próprio servidor está sobrecarregado e seu limite está normal. Ambos podem ser objeto de nova tentativa, mas apenas o 429 vem com a indicação Retry-After.

Quanto tempo o estado 529 costuma durar?

Não é possível prever nem garantir. Por isso, a resposta correta é backoff com limite superior e uma fila, não inserir um tempo de espera fixo no código. Se o caminho tiver tolerância à latência, o fallback assumirá em vez de esperar.

Chamadas que falharam com 529 também são cobradas?

Ao passar pela Kunavo, não. Solicitações encerradas com erro não são cobradas. Em um contrato direto, aplicam-se as regras de cobrança de cada provedor.