Índice
Você já foi interrompido no meio de uma tarefa no Claude Code por um erro assim?
API Error: 529 {"type":"error","error":
{"type":"overloaded_error","message":"Overloaded"}}
# ou
API Error: 500 Internal server error.529 Overloaded significa que a API da Anthropic está temporariamente acima da capacidade (sobrecarregada), e 500 significa que ocorreu um erro inesperado dentro do servidor. Ambos são do lado do servidor — e, o mais importante, não são um erro na sua requisição ou nas suas configurações, nem o esgotamento do seu uso. A documentação oficial afirma claramente que "um 529 não é o seu limite de uso e não conta contra a sua cota". Em outras palavras, são o tipo de erro que normalmente se resolve com "espere um momento e tente de novo".
Os pontos-chave já de cara. (1) 529/500 são do lado do servidor — não é culpa sua (e não consomem a sua cota). (2) O Claude Code já tenta de novo automaticamente até 10 vezes com backoff exponencial antes de mostrar qualquer coisa — quando a mensagem amigável aparece, essas tentativas já se esgotaram. (3) A solução é "verificar a página de status → esperar → trocar de modelo com /model". A capacidade é controlada por modelo, então, mesmo quando o Opus está ocupado, o Sonnet muitas vezes passa.
Isto é do lado do servidor, não é culpa sua
— O Claude Code já está tentando de novo antes de mostrar qualquer coisa
Então a solução é "esperar e tentar de novo / trocar com /model / verificar status.claude.com".
Praticamente não há código nem configuração a corrigir.
1. O que esse erro está dizendo
HTTP 529 (overloaded_error / mensagem "Overloaded") é um sinal de que a API da Anthropic está temporariamente acima da capacidade. A descrição oficial é literalmente "a API está temporariamente sobrecarregada" e "pode ocorrer quando as APIs sofrem alto tráfego de todos os usuários". Significa que não é culpa de nenhuma pessoa em particular, mas sim que a demanda geral excedeu brevemente a oferta.
HTTP 500 (api_error) é um erro interno inesperado do lado da Anthropic. A documentação diz que "não é causado pela sua prompt, configurações ou conta". Relacionado está o 504 (timeout_error), quando uma requisição longa expira (note que a Anthropic documenta o 504, enquanto 502/503 geralmente vêm de infraestrutura upstream, como gateways).
O ponto crucial: "529 e 500 são problemas do lado do servidor e não consomem a sua cota de uso." São totalmente diferentes do usage limit reached da cota do plano e do seu próprio limite de taxa 429 (esclarecemos a diferença no §4). Portanto, não há por que se preparar para corrigir código ou configurações — o padrão é "esperar e tentar de novo".
2. O Claude Code já está tentando de novo por você
Na verdade, antes mesmo de você ver a mensagem de erro, o Claude Code já vinha tentando de novo nos bastidores. Segundo a documentação oficial —
O comportamento de retry automático
Erros de servidor, respostas de sobrecarga (overloaded), timeouts de requisição, throttles temporários de 429 e conexões interrompidas são todos tentados de novo até 10 vezes com backoff exponencial. Durante as tentativas, o spinner mostra uma contagem regressiva Retrying in Ns · attempt x/y. Quando a string amigável API Error: aparece, essas 10 tentativas já se esgotaram.
Então "um 529 piscou, mas seguiu em frente" é normal — o retry automático o absorveu. Por outro lado, se você chega à mensagem amigável ("Repeated 529 Overloaded errors … try again in a moment. If it persists, check https://status.claude.com"), é sinal de que a carga está ruim o suficiente para que nem as tentativas tenham se recuperado. Você pode ajustar as tentativas com CLAUDE_CODE_MAX_RETRIES (padrão 10) e o limite por requisição com API_TIMEOUT_MS (padrão 600000 ms = 10 minutos) — reduza a contagem para falhar rápido em scripts, aumente-a para aguardar durante um incidente mais longo.
3. O que você pode fazer
As medidas para um 529/500 são, na verdade, muito simples. Tente-as nesta ordem.
Esperar, trocar, verificar
/feedback (inclua o request_id para acelerar a investigação).
Na dúvida? 1) esperar → 2) trocar com /model → 3) verificar o status.
Deslocar para horários de menor pico também ajuda. Praticamente não há configuração a corrigir.
Observação: a mensagem "Server is temporarily limiting requests" também é descrita oficialmente como "um throttle de curta duração do lado do servidor, sem relação com o seu limite de uso." Ela também se resolve com uma breve espera e é algo diferente do usage limit da cota do plano.
4. Distinguindo de erros parecidos
A família dos "travou" pode ter causas opostas. Primeiro, separe por "é do lado do servidor ou do seu lado?"
| Erro | Problema de quem | Usa cota? | Solução principal |
|---|---|---|---|
| 529 Overloaded | Lado do servidor (capacidade, afeta todos) | Não | Esperar e tentar de novo, /model, verificar status |
| 500 / 504 | Lado do servidor (erro interno / timeout) | Não | Tentar de novo; se persistir, /feedback |
| 429 Rate limit | Seu lado (limite de taxa da sua chave de API) | Sim (sua taxa) | Reduzir o ritmo, subir de tier, aguardar o retry-after |
| usage limit reached | Seu lado (cota do plano Pro/Max) | Sim (plano) | Esperar o reset; soluções |
| 400 Invalid request | Seu lado (uma requisição inválida) | Não | Corrigir o corpo da requisição |
Um macete: 5xx (incluindo 529) é do lado do servidor = resolve se você esperar. 429 e usage limit têm a ver com a sua "quantidade" = ajuste a taxa ou o plano. 400 tem a ver com o seu "conteúdo" = corrija a requisição. 429 e 529 são especialmente fáceis de confundir, mas o 429 carrega um cabeçalho retry-after e consome cota, enquanto o 529 não tem cabeçalho e não consome cota — coisas diferentes. Para outros erros comuns do Claude Code, veja a compilação de erros.
5. Para desenvolvedores (API/SDK)
Se você roda o seu próprio app sobre a API/SDK, o design correto trata 529/500 como "um evento passageiro que normalmente pode acontecer."
(1) Os SDKs oficiais lançam exceções tipadas (OverloadedError, InternalServerError, etc.) e tentam de novo automaticamente os erros passageiros com backoff exponencial — capture as classes de exceção, não comparações de string. (2) Se você mesmo fizer o retry, use "backoff exponencial + jitter". (3) O cabeçalho retry-after está presente no 429, mas NÃO no 529, então em um 529 espere com o seu próprio backoff, não com um tempo guiado pelo cabeçalho. (4) Tenha um modelo de fallback (o Claude Code tem --fallback-model). (5) Aumente o tráfego gradualmente para evitar o "limite de aceleração" do 429 após um pico de uso. Se você precisa de disponibilidade estável, o Priority Tier e a Message Batches API também são opções. Para o básico, veja O que é uma API de IA.
6. Pico passageiro ou um incidente?
O mesmo 529/500 significa coisas diferentes dependendo de ser "um pico que some na hora" ou "uma queda contínua que se repete."
Um pico passageiro (um ou alguns que se resolvem ao tentar de novo) está dentro da faixa normal de flutuação da demanda. O retry automático geralmente o absorve e não há nada a corrigir do seu lado. Por outro lado, "Repeated 529", ou um 500 que sobrevive às tentativas, é um sinal para suspeitar de um incidente ativo — primeiro verifique o status.claude.com e, se uma queda estiver publicada, esperar a recuperação é a única medida certa. Se um 500 persistir sem incidente publicado, reporte via /feedback com o request_id. De qualquer forma, tudo o que um usuário pode fazer diante de 529/500 é "tentar de novo, trocar com /model, verificar o status e reportar" — e isso é genuinamente o suficiente.
Resumo
O "API Error: 529 Overloaded" e o "500 Internal server error" do Claude Code são eventos do lado do servidor em que a API da Anthropic está temporariamente sobrecarregada ou sofreu um erro interno. Eles não são um erro na sua requisição ou nas suas configurações, não são o esgotamento do seu uso e não consomem cota. O Claude Code tenta de novo automaticamente até 10 vezes com backoff exponencial antes de mostrar qualquer coisa; a mensagem amigável significa que essas tentativas se esgotaram.
A solução é simples: (1) esperar e tentar de novo -> (2) trocar de modelo com /model (a capacidade é por modelo) -> (3) verificar o status.claude.com -> (4) /feedback se um 500 persistir. Eles são diferentes de 429 (sua taxa) e usage limit (seu plano), e o 529 não carrega retry-after. Os desenvolvedores devem projetar em torno disso com o retry automático do SDK, backoff exponencial + jitter e um modelo de fallback. Se se repetir, suspeite de um incidente e verifique a página de status — de qualquer forma, praticamente não há código nem configuração a corrigir. Relacionados: soluções para o usage limit, comparação Opus/Sonnet/Haiku, compilação de erros do Claude Code.
FAQ
Q. O "529 Overloaded" é causado por algo que fiz de errado, ou pelo meu código?
A. Não — é um problema do lado do servidor. Um 529 significa que a API da Anthropic está temporariamente acima da capacidade (congestionamento envolvendo todos os usuários); a sua requisição, configurações e conta não estão envolvidas. A documentação afirma claramente que "um 529 não é o seu limite de uso e não conta contra a sua cota." Normalmente se resolve se você esperar um momento e tentar de novo.
Q. Ele fica me dizendo para tentar de novo — devo ficar repetindo eu mesmo?
A. Em geral, não. O Claude Code já tenta de novo automaticamente até 10 vezes com backoff exponencial antes de mostrar o erro (Retrying in Ns · attempt x/y). A mensagem amigável apareceu porque essas 10 tentativas se esgotaram. Espere um pouco e, para uma prompt longa, basta digitar "tente de novo" para reexecutar com o contexto original. Você pode ajustar a contagem com CLAUDE_CODE_MAX_RETRIES.
Q. Qual é a diferença entre 529 e 429?
A. O 529 é sobrecarga do lado do servidor (afeta todos; não consome nenhuma cota sua), enquanto o 429 é o seu próprio limite de taxa (você excedeu o RPM da sua chave de API, etc. — sobre a sua faixa de taxa). Um indício: o 429 carrega um cabeçalho retry-after, enquanto o 529 não. Um 429 exige ajuste do seu lado (reduzir o ritmo, subir de tier); um 529 só precisa de esperar e tentar de novo ou uma troca com /model.
Q. Por que trocar com /model às vezes funciona?
A. Porque a capacidade (congestionamento) é controlada por modelo. Mesmo que o Opus esteja sob carga alta, o Sonnet pode passar na hora se tiver folga. O próprio Claude Code às vezes sugere uma troca sob carga ("Opus is experiencing high load, please use /model to switch to Sonnet"). Quando você está com pressa, trocar para um modelo mais leve ou diferente com /model é uma solução de contorno rápida.
Q. Continuo recebendo 529/500 sem parar. O que devo fazer?
A. Suspeite de um incidente ativo e verifique o status.claude.com. Se uma queda estiver publicada, tudo o que você pode fazer é esperar a recuperação. Se um 500 persistir sem incidente publicado, reporte via /feedback com o request_id para que a Anthropic possa investigar. Como 529/500 são eventos do lado do servidor, praticamente não há código nem configuração para você corrigir.
