Erro 529 overloaded_error do Claude — causa e estratégia de retry

529 é o único erro do Claude que seu código não causou: a Anthropic está saturada. Você não pode corrigi-lo — apenas absorvê-lo corretamente. Isso significa novas tentativas pacientes com backoff, um modelo de fallback em caminhos sensíveis à latência e, acima de tudo, nenhuma rajada imediata de retry que amplifique o incidente.

O erro

réponse (HTTP 529)

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

Causas e soluções em resumo

Causa	Solução
Saturação do lado do provedor (dias de lançamento, incidentes regionais). Afeta todos os clientes ao mesmo tempo.	Backoff com jitter; consulte a página de status da Anthropic em vez de reimplantar sua aplicação.
Seu próprio pico de carga coincide com uma capacidade que já está sob pressão.	Distribua os processamentos em lote; um atraso de dez minutos geralmente é suficiente.
Confusão com 429: nos logs, um limite de velocidade se parece com isso, mas a causa não tem relação.	429 significa que você excedeu seus limites (o servidor está saudável); 529 significa que o servidor está saturado (seu limite está em ordem). Apenas 429 vem acompanhado de uma indicação Retry-After.
Nenhum fallback definido, então um problema do provedor chega ao usuário final.	Defina uma cadeia de fallback — dentro da mesma família (Sonnet → Haiku), o comportamento permanece semelhante; entre provedores (Claude → GPT), você também sobrevive a uma interrupção completa.

Retomar sem ampliar o incidente

Trate 529 como 429 sem Retry-After: backoff exponencial a partir de ~2 segundos, com jitter, limitado a 30–60 segundos, desista após cerca de cinco tentativas e coloque o trabalho em fila. O jitter é a parte que importa: sem ele, todos os clientes retornam ao mesmo tempo e prolongam exatamente a saturação da qual estão tentando escapar.

Mudar de rota em vez de cair

Nos caminhos sensíveis à latência, defina uma cadeia de fallback. Em um endpoint compatível com OpenAI, basta alterar uma única string — sem segundo SDK, sem segunda conta:

failover.py

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

E só então analisar seu código

Se os 529 aparecerem apenas em um tipo de solicitação enquanto as outras chamadas funcionam ao mesmo tempo, não é um incidente generalizado: verifique se esse caminho envia prompts excepcionalmente grandes ou faz polling em um loop apertado. Se, ao contrário, isso afetar todas as chamadas de uma vez e desaparecer sozinho, era capacidade — e o trabalho cabe ao retry e ao fallback, não a uma reescrita.

Se você estiver chamando pela Kunavo

A Kunavo roteia o Claude por mais de um caminho upstream, e seu catálogo multimodelo torna a troca entre provedores uma simples mudança no nome do modelo, usando a mesma chave e a mesma carteira — o esquema acima não precisa de uma segunda conta. Os 529 que ainda chegam até você nunca são cobrados. Capacidade e preço são duas questões distintas; para a segunda, as tarifas por modelo estão na tabela de preços da API do Claude.

Perguntas frequentes

Um 529 é culpa minha?

Não. É um problema de capacidade do lado do provedor. Suas únicas responsabilidades são não ampliar o incidente (backoff, jitter) e ter uma saída de emergência caso o incidente dure mais do que seu orçamento de latência.

529 ou 429 — qual é a diferença?

429 significa que você excedeu seus limites; o servidor está bem. 529 significa que o próprio servidor está saturado; sua cota está bem. Ambos podem ser repetidos; apenas 429 fornece uma indicação Retry-After.

Quanto tempo dura um período de 529?

Isso não é previsível nem pode ser garantido — por isso a resposta correta é um backoff limitado mais uma fila, e não um atraso fixado no código. Se o seu caminho tiver um orçamento de latência, o fallback assume o controle em vez de aguardar.

As chamadas com 529 são cobradas?

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

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.