Erro 529 da Claude (overloaded_error): causas e tratamento

529 é o único erro da Claude que não é causado pelo seu código. Quem está congestionada é a Anthropic, e você não pode corrigir isso do seu lado. O que pode fazer é "absorver bem" o erro — retry persistente com backoff exponencial, um modelo de fallback para rotas sensíveis à latência e nenhum disparo de retries imediatos que piore a falha. Esses 3 pontos são todo o tratamento necessário.

O erro

レスポンス（HTTP 529）

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

Causas e soluções em resumo

Causa	Solução
Congestionamento do provedor (lançamento de um novo modelo, falha regional). Ocorre simultaneamente para todos os usuários.	Aguarde usando backoff com jitter. Em vez de reimplantar o aplicativo, verifique a página de status da Anthropic.
Seu próprio envio em burst se sobrepôs a uma capacidade já pressionada.	Distribua o processamento em lote ao longo do tempo. Na maioria das vezes, deslocar em 10 minutos resolve.
Confusão com o 429. Eles parecem semelhantes nos logs, mas as causas são completamente diferentes.	429 significa que você excedeu seu limite (o servidor está normal); 529 significa que o servidor está sobrecarregado (saldo e limites estão normais). Apenas o 429 inclui Retry-After.
Nenhum fallback foi definido, então o problema do provedor chega diretamente ao usuário final.	Defina a ordem dos fallbacks. Na mesma família (Sonnet → Haiku), o comportamento é parecido; entre provedores (Claude → GPT), é possível superar uma falha geral.

Faça retries sem piorar a falha

Trate 529 como um "429 sem Retry-After". Comece com backoff exponencial de aproximadamente 2 segundos, use jitter, limite a 30–60 segundos e desista após cerca de 5 tentativas, transferindo para uma fila. A parte que funciona é o jitter. Sem ele, todos os clientes retornam no mesmo instante e prolongam exatamente o congestionamento do qual deveriam sair.

Não descarte; redirecione

Prepare uma cadeia de fallbacks para rotas sensíveis à latência. Em um endpoint compatível com OpenAI, você só precisa mudar uma string — não é necessário adicionar SDKs nem contas:

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          # 過負荷 — 次の候補へ
    raise last

Suspeite do seu próprio código por último

Se apenas um tipo específico de solicitação recebe 529 e outras chamadas no mesmo horário funcionam, isso não é uma falha geral. Verifique se essa rota está enviando um prompt anormalmente grande ou disparando chamadas em um loop curto. Por outro lado, se todas as chamadas recebem 529 de uma vez e a situação se resolve naturalmente depois de algum tempo, a causa é capacidade. Nesse caso, o que precisa ser ajustado é retry e fallback, não refatoração.

Se você estiver chamando pela Kunavo

A Kunavo distribui o Claude por várias rotas upstream, e o catálogo multimodelo permite um fallback entre provedores alterando apenas o nome do modelo, com a mesma chave e o mesmo saldo. Não é necessária uma segunda conta para o código acima. Mesmo assim, um 529 que seja retornado não será cobrado. Capacidade e preço são problemas diferentes. Quanto ao segundo, consulte o preço unitário de cada modelo na tabela de preços da Claude API.

Perguntas frequentes

529 é culpa minha?

Não. É um problema de capacidade do provedor. Sua responsabilidade tem apenas duas partes — não amplificar a falha (backoff e jitter) e preparar um destino de escape quando a falha ultrapassar a latência aceitável.

Qual é a diferença entre 529 e 429?

429 significa que você excedeu seu limite, enquanto o servidor está normal. 529 significa que o servidor está sobrecarregado, enquanto seus limites e saldo estão normais. Ambos podem ser repetidos, mas apenas 429 traz a indicação Retry-After.

Quanto tempo um 529 costuma durar?

Não é previsível nem pode ser garantido. Por isso, a resposta correta é "backoff limitado + fila", não escrever um tempo de espera fixo no código. Se essa rota tiver um prazo de latência, não espere: deixe o fallback assumir.

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

Pela Kunavo, não. Solicitações encerradas com erro não são cobradas. Em contratos diretos, aplicam-se as regras de cobrança de cada provedor.

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.

Erro 529 overloaded_error da Claude API — significado e tratamento correto