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

O 529 é o único erro do Claude que seu código não causou: a própria Anthropic está sobrecarregada. Você não pode corrigi-lo — só pode absorvê-lo com elegância. Isso significa novas tentativas pacientes, um modelo de fallback e nunca ampliar o incidente com tempestades de novas tentativas imediatas.

O erro

response (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)	Use backoff com jitter; verifique a página de status do provedor em vez de reimplantar o aplicativo.
Sua rajada de tráfego chegando durante um incidente leve	Distribua os trabalhos em lote; um atraso de 10 minutos geralmente resolve.

Faça novas tentativas como um bom cidadão

Trate o 529 como 429-sem-retry-after: backoff exponencial começando em aproximadamente 2s, jitter, limite de 30–60s, desista após aproximadamente 5 tentativas e coloque o trabalho em fila. O trecho de backoff do nosso guia de 429 trata o 529 no mesmo ramo.

Faça failover em vez de falhar para baixo

Para caminhos sensíveis à latência, defina um fallback: a mesma família (Sonnet → Haiku) mantém o comportamento próximo; entre provedores (Claude → GPT), você sobrevive a um incidente que afete todo o provedor. Em um endpoint compatível com OpenAI, basta alterar uma string:

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          # saturated — try the next tier
    raise last

Se você estiver chamando pela Kunavo

A Kunavo roteia o Claude por mais de um caminho upstream e seu catálogo multimodelo transforma o failover entre provedores em uma alteração da string do modelo usando a mesma chave e a mesma carteira — o padrão de failover acima não precisa de uma segunda conta. Os 529 que chegam até você continuam nunca sendo cobrados. Capacidade e preço são perguntas separadas; para a segunda, as tarifas por modelo estão na tabela de preços da Claude API da Anthropic.

Perguntas frequentes

Um 529 é culpa minha?

Não. É capacidade do lado do provedor. Suas únicas responsabilidades são não amplificá-lo (backoff e jitter) e ter para onde fazer failover se o incidente durar mais que seu orçamento de latência.

529 versus 429 — qual é a diferença?

429 significa que você ultrapassou seus limites (o servidor está normal); 529 significa que o próprio servidor está sobrecarregado (sua cota está normal). Ambos permitem novas tentativas; apenas o 429 vem com uma indicação de retry-after.

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.