O erro "API Error: 529 Overloaded" aparece no meio de uma sessão do Claude Code e a reação natural é apertar enter de novo. Não adianta, e não é a sua cota que acabou: é a API da Anthropic temporariamente sobrecarregada, e a documentação oficial diz isso com todas as letras. Mais do que isso, a CLI já está tentando de novo sozinha enquanto você olha para a tela. O estrago de verdade está em outro lugar, nos agentes que você dispara em paralelo.
O que significa "529 Overloaded"?
Significa que a API da Anthropic está temporariamente sobrecarregada. Não é erro do seu código, da sua chave nem do seu plano.
Na documentação oficial de erros da Claude API, o código 529 tem o tipo overloaded_error e a definição literal: "The API is temporarily overloaded". O aviso logo abaixo é a parte que tira a dúvida: "529 errors can occur when the API experiences high traffic across all users". Tráfego alto de todos os usuários, não o seu.
A resposta chega neste formato:
{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "Overloaded"
},
"request_id": "req_011CeME4MStM56TRJaC3dWRJ"
}Guarde o request_id. Ele vem em toda resposta da API, também no header request-id, e é o que o suporte da Anthropic pede para rastrear uma requisição específica.
É a minha cota ou é a Anthropic?
É a Anthropic. O código que significa "a sua cota" é outro: 429. Confundir os dois faz você mexer no lugar errado, trocando de modelo ou de plano por um problema que não é seu.
| Código | Tipo | De quem é o problema | O que fazer |
|---|---|---|---|
429 | rate_limit_error | Seu. A organização bateu em rate limit ou no teto de gasto | esperar a janela, revisar limite ou plano |
529 | overloaded_error | Da Anthropic. Tráfego alto de todos os usuários | deixar o retry automático trabalhar |
500 | api_error | Da Anthropic. Erro interno inesperado | retry com backoff exponencial; persistindo, abrir suporte com o request_id |
504 | timeout_error | Requisição longa demais | usar a Messages API em streaming |
Para confirmar que é geral e não só com você, veja status.claude.com antes de sair mexendo na configuração.
Preciso ficar tentando de novo?
Não. A CLI já faz isso sozinha, e mostra na própria tela quantas vezes já tentou.
A linha que aparece, registrada na issue #91817 do repositório oficial, é esta:
✻ 529 Overloaded · Retrying in 4s · attempt 6/10São até 10 tentativas, com espera crescente entre elas. Fechar o terminal e abrir de novo no meio disso joga fora as tentativas já feitas e recomeça a contagem do zero, que é o oposto do que você quer.
Se você chama a API direto pelo SDK em vez da CLI, o padrão é mais conservador. Os SDKs oficiais retentam falhas transitórias com backoff exponencial duas vezes por padrão, respeitando o header retry-after quando ele vem. Dá para subir esse número no cliente:
client = anthropic.Anthropic(max_retries=5)
Por que meus agentes em paralelo falham todos juntos?
Porque eles saem juntos. Quando um orquestrador dispara vários agentes de uma vez, todas as primeiras requisições batem na API no mesmo instante, e uma sobrecarga momentânea derruba o lote inteiro em vez de um ou outro.
O padrão está descrito na issue #90043, cujo título já é o diagnóstico: "Fan-out launches agents without stagger, causing correlated 529 failures". Sem jitter entre os lançamentos, as falhas ficam correlacionadas.
A própria documentação da Anthropic recomenda o contrário, ao falar de limites de aceleração: "ramp up your traffic gradually and maintain consistent usage patterns". Subir o tráfego aos poucos, em vez de num pico. Na prática, basta espalhar os disparos:
import random, time
for tarefa in tarefas:
lancar(tarefa)
time.sleep(random.uniform(0.5, 2.0))Dois segundos de atraso no lançamento custam menos que refazer o lote todo.
Como não perder o trabalho quando um subagente morre?
Esse é o custo escondido do 529, e é o mais caro. Quando um subagente em segundo plano morre com esse erro, ele não devolve resultado parcial: a tarefa volta como falha e o único caminho é relançar do zero. A issue #89267 descreve exatamente isso, e o segundo run repete, e paga de novo, todo o trabalho que o primeiro já tinha feito.
Enquanto o comportamento não muda, a defesa é de arquitetura: quebre tarefa longa em etapas que gravam resultado em disco ao terminar, em vez de uma única tarefa de uma hora que só entrega no fim. Assim uma sobrecarga de 30 segundos custa uma etapa, não a tarefa inteira.
Vale o mesmo cuidado com automação que roda sem ninguém olhando: uma tarefa agendada que falha com 529 pode ser contabilizada como execução concluída e disparar notificação de sucesso, comportamento relatado na issue #92423. Se o seu cron confia no código de saída, confira também se houve entrega de verdade.
E quando o 529 volta todo dia?
Aí não é mais um incidente, é uma dependência. Todas as saídas acima continuam valendo, mas nenhuma delas muda o fato de que a fila é controlada por outra empresa.
Se esse erro voltar amanhã, o problema não é o seu setup, é depender de uma infraestrutura só. A Verboo Code é um fork da Claude Code, então o fluxo de terminal é o mesmo que você já usa, rodando em outra infraestrutura: npm install -g @verboo/code e depois verboo /login. A sua fila anda enquanto a outra espera o status page.
