Claude Code 529 Overloaded: causas, configuração de novas tentativas e soluções

Wokey Team · 2026-09-24

Resposta curta: um 529 significa que o modelo upstream está sem capacidade agora ("overloaded"). Não tem nada a ver com seu saldo, sua cota ou sua chave de API. O Claude Code já tentou de novo várias vezes antes de mostrar o erro. A correção mais rápida é trocar de modelo com /model, porque a capacidade é contada por modelo. Se não tiver pressa, espere alguns minutos e envie de novo.

O erro exato

No Claude Code você vê:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

A documentação do Claude Code destaca três pontos sobre ele:

• É um problema temporário de capacidade que afeta todos os usuários.
• O Claude Code já tentou de novo várias vezes antes de mostrá-lo.
• Um 529 não é o seu limite de uso e não conta contra a sua cota.

Quando você se conecta por um gateway com ANTHROPIC_BASE_URL, a última frase cita o host do gateway em vez de status.claude.com.

De onde vem um 529 na Wokey

A Wokey nunca gera um 529 por conta própria; o status sempre vem do modelo upstream. A Wokey lida com ele em três etapas:

1. Quando o upstream informa sobrecarga (por exemplo, o overloaded_error da Anthropic), a Wokey primeiro tenta de novo sua requisição em outra rota upstream para o mesmo modelo. Você não vê isso.

2. Só se a nova tentativa também estiver sobrecarregada a Wokey repassa o status do upstream. O status HTTP continua 529. O corpo usa o formato de erro padrão da Wokey, com o texto do próprio upstream em message:

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. Se a sobrecarga acontecer depois que a resposta já começou o streaming, ela chega como um evento error dentro do stream em vez de um HTTP 529.

Portanto, um 529 via Wokey significa que várias rotas upstream do mesmo modelo estavam sobrecarregadas ao mesmo tempo, geralmente durante um pico do lado do provedor. Essas respostas não trazem o cabeçalho Retry-After; seu cliente tenta de novo seguindo o próprio esquema de backoff.

Como diferenciar de outros erros

Só 529 e 503 significam "o upstream está ocupado". Os outros exigem uma ação sua.

O que fazer

1. Espere e envie de novo. A sobrecarga costuma passar em minutos, e as novas tentativas automáticas do Claude Code já cobrem picos curtos.

2. Troque de modelo com /model. A capacidade é contada por modelo, então quando o Opus está sobrecarregado o Sonnet muitas vezes ainda funciona. Rode /model na sessão e escolha outro modelo; não é preciso reiniciar.

3. Para tarefas longas sem supervisão, insista mais nas novas tentativas. Adicione isto ao bloco env de ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 faz o Claude Code tentar de novo erros 429 e 529 indefinidamente, com espera de até 5 minutos entre as tentativas. Serve para tarefas que ficam rodando durante a noite.
• Para apenas algumas tentativas a mais, defina CLAUDE_CODE_MAX_RETRIES. O padrão é 10 e o máximo é 15.

4. No seu próprio código, deixe margem para novas tentativas em 529. Os SDKs oficiais da Anthropic tentam de novo erros 5xx, incluindo 529, duas vezes por padrão. Para tarefas em lote, aumente max_retries e adicione backoff exponencial em volta da chamada.

Vendo um 529 no Codex

O Codex trata erros 5xx, incluindo 529, como passíveis de nova tentativa:

• A camada HTTP tenta de novo 4 vezes por padrão (o request_max_retries do provedor).
• Depois, a camada de stream tenta até mais 5 vezes (stream_max_retries).
• Se tudo isso falhar, o erro começa com unexpected status 529, seguido do corpo da resposta.

Um code igual a upstream_overloaded nesse corpo indica a sobrecarga do upstream descrita acima. A correção é a mesma: espere, ou troque de modelo no config.toml. Para a configuração completa do Codex, veja o guia do config.toml do Codex.