Erros do Claude Code e como corrigi-los

Guias detalhados para cada erro

• Erro de API: 500 (Erro interno do servidor) — indisponibilidade, falhas específicas de modelos, compactação em 0%.
• Sobrecarga / Erro de API 529 — capacidade, novas tentativas, picos de subagentes.
• Erro de API 400 — prompt longo demais, simultaneidade no uso de ferramentas e outras solicitações rejeitadas.
• Erros de OAuth — tempo limite de 15000ms excedido, código de status 500 no login.
• Processo encerrado com código 1 — falhas na extensão do VS Code e no aplicativo para desktop.
• Limite de requisições atingido / 429 — os três limites e como aumentá-los.
• Prompt longo demais / limite de contexto atingido — o que preenche a janela, falsos alarmes, falhas de compactação, limites de comprimento de claude.ai.
• Limite de uso atingido — janelas de sessão, semanais e do Opus, "limites de uso da API especificados", "saldo de créditos insuficiente".
• Autenticação 401 / 403 — credenciais inválidas, chave de API inválida, "Login não realizado", host_not_allowed.
• Erros de conexão — ECONNRESET, "Aguardando resposta da API", certificados, proxies, variáveis de novas tentativas.
• Travamentos, bloqueios, falta de resposta — onde está travado, teclas para sair, bugs conhecidos de travamento, memória.
• claude.ai não funciona — "Algo deu errado", restrições de capacidade, limite de 5 horas, erros de login.

Erro de API 500 (e 529 de sobrecarga)

Um 500 é uma falha no serviço upstream; 529 é o código explícito da Anthropic para "modelo no limite da capacidade". Nenhum dos dois é causado pelo seu prompt. O Claude Code tenta novamente algumas vezes por conta própria; se desistir, espere um minuto e retome com claude -c. Mudar de categoria com /model costuma funcionar imediatamente porque a capacidade é definida por modelo. Neste gateway, uma conta upstream saturada é substituída automaticamente por outra, por isso os erros 529 são mais raros aqui do que ao usar uma única conta.

Erro de API 400 — solicitação inválida / contexto longo demais

No Claude Code, um 400 quase sempre significa que a conversa, somada aos arquivos que ele leu, já não cabe na janela do modelo. /compact resume o histórico; /clear começa do zero; ou mude para uma (1M) variante do modelo. Outros erros 400: um parâmetro não compatível após uma atualização (execute claude update), ou uma imagem ou arquivo que o modelo não aceita.

Erro de API 429 — limite de requisições / taxa excedida

Aplicam-se três limites: requisições por minuto, tokens por minuto e requisições simultâneas. As sessões com agentes atingem primeiro o limite de simultaneidade — cada subagente é uma requisição paralela em streaming que ocupa uma vaga até terminar. Reduza o paralelismo, aguarde o intervalo de retry-after e, para trabalho contínuo, solicite um limite maior de simultaneidade na sua conta do gateway.

Erro de OAuth: tempo limite de 15000ms excedido

O fluxo de /login não conseguiu acessar o serviço de autenticação da Anthropic em 15 segundos. É um problema de rede, não de conta: um proxy corporativo, uma VPN que interrompe o callback ou uma região onde o endpoint de autenticação é lento. Tente novamente uma vez; se persistir, configure HTTPS_PROXY para sua rede ou dispense completamente o OAuth usando uma chave de API — com ANTHROPIC_API_KEY (e ANTHROPIC_BASE_URL para um gateway), o Claude Code nem sequer abre o fluxo de login.

Erro de OAuth: solicitação falhou com código de status 500

O serviço de autenticação respondeu com um erro de servidor durante o login ou a renovação do token. Nada do seu lado causa isso; espere alguns minutos e execute /login novamente. Se precisar trabalhar agora, o acesso por chave de API descrito acima dispensa o OAuth, e claude setup-token em uma máquina onde o login funciona gera um token de longa duração que você pode transferir para aquela onde ele não funciona.

Erro: processo do Claude Code encerrado com código 1

Isso é a extensão do IDE ou o aplicativo para desktop informando que a CLI iniciada por ele falhou na inicialização — o erro real está um nível abaixo. Abra um terminal e execute claude diretamente: você verá a mensagem real, que quase sempre indica uma versão do Node.js inferior a 18, um PATH danificado após uma instalação via npm, uma instalação nativa corrompida ou um settings.json com JSON inválido (uma vírgula fora de lugar em um bloco de hooks é um caso clássico). claude doctor verifica os três primeiros; um linter de JSON detecta o quarto. Reinstalar com o instalador nativo resolve a maioria dos demais problemas.

401 / erros de autenticação

invalid x-api-key ou authentication_error significa que a chave não pertence ao endpoint. Se ANTHROPIC_BASE_URL aponta para o gateway, a chave deve ser uma chave de gateway; uma chave do console da Anthropic será recusada, e o inverso também se aplica. /status mostra qual endpoint e qual chave estão ativos. Se você usa /login e uma chave de API ao mesmo tempo, a chave tem prioridade. Loops de renovação de token, Not logged in após um login bem-sucedido e erros 403 de proxies estão na página de 401 / 403.

"Nenhum upstream saudável"

Não é um erro de API: é o balanceador de carga à frente de um serviço informando que nenhum backend está disponível. No endpoint oficial, significa uma indisponibilidade; em um gateway, significa que todo o conjunto de upstreams está indisponível ou com o tráfego limitado. Aguarde e tente novamente; não altere sua configuração.

Claude Code não funciona de jeito nenhum

• Inicia e depois encerra silenciosamente → execute claude /doctor; geralmente é um problema de versão do Node ou de PATH.
• Trava na inicialização ou durante a sessão → veja travamentos e sessões bloqueadas e erros de conexão.
• command not found → veja o guia de instalação.
• Ferramentas falham com erros de permissão → /permissions, ou --allowedTools em scripts.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Perguntas frequentes

A AI Prime Tech é um gateway de API independente e não é afiliada, endossada nem patrocinada pela Anthropic. “Claude” e “Claude Code” são marcas comerciais da Anthropic. Os recursos do Claude Code descritos aqui seguem a documentação pública da Anthropic no momento da redação e mudam com frequência; os preços e as listas de modelos nesta página são obtidos das configurações atuais deste gateway.