Erro 529 overloaded_error da API Claude — o que significa e como lidar com ele

Tentar novamente sem agravar a falha

Trate 529 como um 429 sem Retry-After: backoff exponencial a partir de cerca de 2 segundos, com jitter, limitado a 30–60 segundos; depois de aproximadamente cinco tentativas, desista e coloque o trabalho em uma fila. O jitter é essencial: sem ele, todos os clientes retornam ao mesmo tempo e prolongam exatamente a sobrecarga da qual tentam sair.

Desviar em vez de falhar

Para caminhos sensíveis à latência, defina uma cadeia de fallback. Em um endpoint compatível com OpenAI, isso é apenas uma string alterada — nenhum segundo SDK, nenhuma segunda 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          # überlastet — nächste Stufe versuchen
    raise last

Só então examine seu próprio código

Se 529 ocorrer apenas em um tipo de solicitação e outras chamadas no mesmo momento funcionarem, não é uma falha generalizada do provedor: verifique se esse caminho envia prompts excepcionalmente grandes ou dispara em um loop apertado. Se ocorrer simultaneamente em todas as chamadas e desaparecer sozinho, foi capacidade — então o trabalho pertence ao retry e ao fallback, não a uma refatoração.

Um 529 é culpa minha?

Não. É um problema de capacidade do lado do provedor. Sua responsabilidade se limita a não agravar a falha (backoff, jitter) e ter um destino alternativo caso o incidente dure mais que seu orçamento de latência.

529 ou 429 — qual é a diferença?

429 significa que você excedeu seus limites; o servidor está saudável. 529 significa que o próprio servidor está sobrecarregado; seu limite está em ordem. Ambos podem ser repetidos; apenas 429 traz uma indicação Retry-After.

Quanto costuma durar uma fase de 529?

Não é previsível nem algo que se possa garantir — por isso, a resposta correta é um backoff limitado junto com uma fila, não um tempo de espera codificado na aplicação. Se seu caminho tem um orçamento de latência, use o fallback em vez de esperar.

As chamadas 529 malsucedidas são cobradas?

Na Kunavo, não: uma solicitação que termina com erro não é cobrada. Em um contrato direto, isso depende das regras de cobrança do provedor correspondente.