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

O 529 é o único erro do Claude que seu código não provocou: quem está saturada é a Anthropic. Você não pode corrigi-lo — apenas absorvê-lo com elegância. Isso significa retries pacientes com backoff, um modelo de reserva nas rotas sensíveis à latência e, acima de tudo, nada de rajadas de retries imediatos que amplifiquem o incidente.

O erro

resposta (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 fazer um novo deploy da aplicação.
Seu próprio pico de carga incide sobre uma capacidade já pressionada.	Distribua os trabalhos em lotes; dez minutos de atraso geralmente resolvem o problema.
Confusão com 429: nos logs, um limite de taxa parece semelhante, mas a causa é completamente diferente.	429 significa que você excedeu seus limites (o servidor está bem); 529 significa que o servidor está saturado (sua cota está bem). Somente 429 traz uma dica Retry-After.
Não há uma reserva definida, então um problema do provedor chega até o usuário final.	Defina uma cadeia de reserva — dentro da mesma família (Sonnet → Haiku), o comportamento permanece parecido; entre provedores (Claude → GPT), você sobrevive a um incidente completo.

Fazer retry sem amplificar o incidente

Trate o 529 como um 429 sem Retry-After: backoff exponencial a partir de cerca de 2 segundos, com jitter, limite de 30–60 segundos, desistência após cerca de cinco tentativas e enfileiramento do trabalho. O jitter é a parte importante: sem ele, todos os clientes retornam ao mesmo tempo e prolongam justamente a saturação da qual tentam sair.

Alternar em vez de falhar

Nas rotas sensíveis à latência, defina uma cadeia de reserva. Em um endpoint compatível com OpenAI, isso é apenas trocar uma cadeia de texto — sem um segundo SDK e sem uma 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          # saturado — probar el siguiente nivel
    raise last

E só então analisar seu código

Se os 529 aparecerem apenas em um tipo de solicitação enquanto as demais chamadas funcionam ao mesmo tempo, não é um incidente geral: verifique se essa rota envia prompts excepcionalmente grandes ou dispara em um loop fechado. Se, por outro lado, afetar todas as chamadas de uma vez e desaparecer sozinho, era capacidade — e então o trabalho pertence ao retry e à reserva, não a uma refatoração.

Se você estiver chamando pela Kunavo

O Kunavo roteia o Claude por mais de um caminho de origem, e seu catálogo multimodelo transforma a alternância entre provedores em uma mudança no nome do modelo usando a mesma chave e a mesma carteira — o padrão acima não precisa de uma segunda conta. Os 529 que ainda chegarem até você nunca são cobrados. Capacidade e preço são perguntas distintas; para a segunda, as tarifas por modelo estão em preços do Claude.

Perguntas frequentes

Um 529 é culpa minha?

Não. É capacidade do lado do provedor. Suas únicas responsabilidades são não amplificar o incidente (backoff, jitter) e ter uma saída de reserva 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á bem. 529 significa que o próprio servidor está saturado; sua cota está bem. Ambos permitem retry; somente 429 vem com uma dica Retry-After.

Quanto normalmente dura um episódio de 529?

Não é previsível nem pode ser garantido — por isso a resposta correta é um backoff com limite superior mais uma fila, e não uma espera gravada no código. Se sua rota tiver um orçamento de latência, a reserva assume em vez da espera.

As chamadas que terminam em 529 são cobradas?

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

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.