Índice
- 1. Os "comandos de diagnóstico" para rodar primeiro
- 2. Autenticação e login
- 3. Uso e limites de taxa (o mais comum)
- 4. Contexto e tokens
- 5. Servidor e modelo
- 6. Instalação, PATH e atualização
- 7. Rede e proxy
- 8. MCP (servidores conectados)
- 9. Permissões e ferramentas
- 10. Outros (thinking / imagem-PDF / IDE)
- 11. Guia rápido erro → solução
- Resumo
- FAQ
Você está trabalhando no Claude Code e ele para de repente com um erro — "faça login novamente", "limite de taxa", "prompt longo demais", "o MCP não conecta". São tantos tipos que pesquisar cada um no Google vira um saco. Este artigo é uma referência prática que cataloga os erros que você costuma encontrar no Claude Code, com a causa e o comando a rodar para cada um.
A conclusão primeiro: para a maioria dos erros, rodar claude doctor (diagnóstico completo), /status (sua autenticação atual) e /context (detalhamento do contexto) primeiro vai estreitar a causa. E os mais comuns se agrupam em quatro famílias: ① uso/limites de taxa, ② estouro de contexto, ③ autenticação expirada, ④ falhas de conexão do MCP. Abaixo, cada categoria está organizada como "sintoma → causa → comando de solução". Salve nos favoritos e pule para a seção relevante quando estiver travado.
Na dúvida, estes 3 comandos
— a maioria dos erros começa por isolar a causa
As quatro famílias: ① uso/limites de taxa ② estouro de contexto ③ autenticação expirada ④ falha de conexão do MCP.
E discretamente, "atualizar para a versão mais recente" claude update resolve muitos bugs.
* Os comandos e soluções aqui se baseiam na documentação oficial do Claude Code (em 2026). O Claude Code é atualizado rápido, e nomes de comandos e o texto das mensagens podem mudar. Confirme o mais recente com claude doctor e a documentação oficial.
1. Os "comandos de diagnóstico" para rodar primeiro
Antes de mergulhar em erros específicos, conhecer os comandos de diagnóstico que ajudam a isolar a causa permite identificar a maioria dos problemas rapidamente.
| Comando | O que mostra / faz |
|---|---|
claude doctor | Verificação completa de instalação, configurações, servidores MCP, uso de contexto |
/status | O método de autenticação ativo no momento (Pro / Max / Team / chave de API) |
/context | Detalhamento do contexto (system prompt, histórico, arquivos, ferramentas MCP) |
/usage | Limites do plano atual e horários de reset |
/permissions | Lista de regras de permissão (allow/deny) e suas origens |
/mcp | Status de conexão dos servidores MCP e contagem de ferramentas expostas |
/feedback | Reportar um bug à Anthropic com o log da conversa |
2. Autenticação e login
A família do "estava funcionando e de repente pede para eu fazer login". A armadilha clássica é uma chave de API em variável de ambiente sobrepondo sua assinatura.
| Sintoma | Causa | Solução |
|---|---|---|
| Not logged in · Please run /login | Nenhuma credencial disponível nesta sessão (um login salvo que não pôde ser renovado aparece como Login expired · Please run /login) | /login. Se repetir, verifique o relógio do sistema e o bloqueio do Keychain |
| Invalid API key · Fix external API key | A API rejeitou uma chave de ANTHROPIC_API_KEY ou do apiKeyHelper (muitas vezes uma chave antiga) | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | Saiu de todos os lugares / um admin removeu o acesso (revoked); falha na renovação automática (expired) | /login. Se voltar na mesma sessão, /logout → /login. Se acontecer a cada início, suspeite do relógio |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | Uma ANTHROPIC_API_KEY antiga de uma org desativada está em uso. Sem variável de ambiente, a org desativada é a do seu /login | Remova a chave do perfil do shell (.zshrc etc.) → /login → confirme com /status. Sem variável de ambiente, contate o suporte ou entre com outra conta |
| 403 Forbidden (after login) | Assinatura expirada / função ausente / interferência de proxy | Verifique assinatura e função no Console. Para proxies, defina HTTPS_PROXY |
Regra prática: uma chave de API em variável de ambiente tem precedência sobre o login da assinatura. Se você definiu ANTHROPIC_API_KEY para um job de CI e esqueceu, seu plano pessoal Pro/Max é ignorado. Verificar "qual credencial está ativa" com /status primeiro é o movimento certo. Para um aprofundamento nas soluções de autenticação e login (a precedência de ANTHROPIC_API_KEY, a expiração do token, o Keychain e mais), veja as causas e soluções dos erros de autenticação e login.
3. Uso e limites de taxa (o mais comum)
A reclamação mais comum com o Claude Code. Segundo o guia oficial de custos (Manage costs effectively), cada turno do Claude Code carrega conteúdo de arquivos, chamadas de ferramentas e raciocínio em várias etapas, então uma única sessão de depuração pode consumir mais do que um dia de chat. Por isso você atinge os limites mais rápido do que parece.
3 ações quando você "atinge o limite"
/usage para limites e horário de reset, /status para a credencial/model para um modelo mais leve, /compact para encolher o histórico, desative MCP não usados
Atenção: "Server is temporarily limiting requests" é um estrangulamento de curta duração do servidor, não o limite do seu plano. Basta esperar e tentar de novo.
Não confunda com os limites de plano (sessão/semanal).
Mais: "API Error: Request rejected (429)" significa que você atingiu o limite de taxa da sua chave de API (ou do seu projeto no Amazon Bedrock / Google Cloud); se a ideia era usar a assinatura, confira em /status se há uma ANTHROPIC_API_KEY perdida. "Credit balance is too low" significa que o saldo pré-pago do Console acabou, ou que as requisições saem por uma chave de API do Console quando você queria usar a assinatura (recarregue, ou confira a chave em /status e remova-a). Note que, em março de 2026, usuários Pro e Max reclamaram que seus limites do Claude Code acabavam muito mais rápido do que o esperado, e a Anthropic reconheceu que investigava o problema como prioridade máxima (The Register, 31 de março de 2026). Se voltar a acontecer, atualize para a versão mais recente, meça com /usage e abra /feedback se necessário. Para economia sistemática de tokens, veja economia de tokens em IA e economia de tokens no Claude Code. Para entender como o "usage limit reached" funciona (a janela de 5 horas e a janela semanal) e o que fazer ao atingir o limite, veja o guia dedicado sobre usage limit reached.
4. Contexto e tokens
Isso aparece quando você lida com reuniões longas ou arquivos enormes.
| Sintoma | Causa | Solução |
|---|---|---|
| Prompt is too long | Conversa + arquivos excedem a janela de contexto | /compact (resumir), /clear (reiniciar), /context para ver o detalhamento, desative MCP não usados via /mcp |
| Error during compaction: Conversation too long | Espaço livre insuficiente para a saída da compactação | Esc duas vezes para retroceder alguns turnos, depois /compact. Se ainda travar, /clear |
| Autocompact is thrashing | Uma saída enorme reenche o contexto logo após a compactação | Leia arquivos grandes por intervalo de linhas / /compact keep only <focus> / mova para um subagente |
O truque é nunca ler um arquivo enorme por inteiro. Passe logs e dados em pequenos pedaços por intervalo de linhas. Entender a ideia de janela de contexto torna essa classe de erro muito mais rara. Para as causas e soluções detalhadas do erro Prompt is too long (a janela de 200K vs 1M, o uso de subagentes), veja o artigo dedicado.
5. Servidor e modelo
| Sintoma | Causa | Solução |
|---|---|---|
| 500 Internal server error | Falha temporária do lado da Anthropic | Verifique status.claude.com → tente de novo após 1 min |
| 529 Overloaded (repeated) | API temporariamente em capacidade máxima | Espere alguns minutos. Troque de modelo com /model para distribuir a carga |
| Request timed out | Sem resposta dentro do padrão de 10 min | Divida a tarefa. Em conexão lenta, aumente API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | Nome de modelo errado ou fora do seu plano | /model para reselecionar. Verifique uma ANTHROPIC_MODEL antiga na env var |
| Claude Opus is not available with the Claude Pro plan | Modelo selecionado fora do seu plano | /model para um disponível. Após mudar de plano, /logout→/login |
Por que 529 Overloaded / 500 são do lado do servidor e não consomem sua cota, como funciona a repetição automática (até 10 vezes) e qual a diferença em relação ao 429, explicamos em 529 Overloaded / 500: causas e soluções.
6. Instalação, PATH e atualização
| Sintoma | Causa | Solução |
|---|---|---|
| command not found: claude | Diretório de instalação fora do PATH | Adicione ~/.local/bin (Win: %USERPROFILE%\.local\bin) ao PATH |
| Install fails (HTML error, etc.) | Proxy / bloqueio de região | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | Inspeção TLS de proxy corporativo / CA ausente | Aponte NODE_EXTRA_CA_CERTS=/path/ca.pem. NUNCA defina NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Várias instalações do Claude Code (versões divergentes, comportamento inesperado) | Duplicatas entre native, npm, Homebrew, WinGet etc. | Verifique com which -a claude (Windows: where.exe claude) e mantenha uma; a instalação native em ~/.local/bin/claude é a recomendada. Ex. npm uninstall -g @anthropic-ai/claude-code |
| Bugs de uma versão antiga | Não atualizado | claude update (a solução número um que resolve muitos bugs) |
| O app de desktop diz "Não é possível abrir este aplicativo" | O pacote MSIX ficou registrado pela metade durante uma atualização (Windows) | Encerre os processos residentes e use o Reparar nas Configurações. explicação completa |
As causas e correções de command not found: claude (PATH, conflitos de várias instalações, permissões do npm, a cilada de usar a shell errada no Windows) estão detalhadas em como resolver o erro "command not found" de instalação e PATH.
7. Rede e proxy
Comum em redes corporativas e VPNs. Primeiro confirme a acessibilidade com curl -I https://api.anthropic.com.
| Sintoma | Causa | Solução |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | Offline / bloqueio de VPN / proxy não configurado | Defina HTTPS_PROXY=http://proxy:8080. Peça ao TI para liberar api.anthropic.com |
| SSL certificate verification failed (corporate) | Certificado de interceptação autoassinado | Pegue o bundle de CA com o TI e defina NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | Fora da allowlist do ambiente cloud | Configure o acesso de rede como Custom e libere o domínio de destino |
| Connection lost mid-response (antes da v2.1.227: Connection closed mid-response) | Conectou e o stream já fluía quando a conexão foi cortada | A saída parcial é mantida: responda continue. Se repetir, veja claude --version e atualize |
Para um aprofundamento sobre a configuração do proxy, certificados TLS (NODE_EXTRA_CA_CERTS), domínios da allowlist e por que NODE_TLS_REJECT_UNAUTHORIZED=0 é perigoso, veja causas e correções do erro de conexão e proxy. Connection lost mid-response (antes, Connection closed mid-response) é outro problema, posterior à chegada da requisição: causas e solução quando a resposta é cortada no meio reúne os passos de isolamento e o que cada versão corrigiu.
8. MCP (servidores conectados)
Você encontra estes assim que começa a usar servidores MCP. Verifique o status primeiro com /mcp.
| Sintoma | Causa | Solução |
|---|---|---|
| Server failed to connect / Pending approval | Servidor caiu / inacessível / autenticação necessária | /mcp para o status. stdio: verifique se o comando existe + é executável; HTTP: verifique URL/headers de autenticação |
| Tool not found | Conectado mas sem ferramentas expostas / nome errado | /mcp para confirmar a contagem de ferramentas, claude mcp get <name> para a saúde |
| Reconnection attempts exhausted | Servidor HTTP/SSE fora do ar após 5 tentativas | Confirme que o servidor está no ar, reconecte manualmente em /mcp. Para stdio, reinicie claude |
| MCP server timeout | A inicialização não termina dentro do MCP_TIMEOUT (padrão de 30 s) | Aumente em ms, por ex. MCP_TIMEOUT=60000 claude. O "timeout" do .mcp.json é o limite de execução de cada ferramenta, não a espera de inicialização |
Para soluções de acordo com o status da conexão MCP —failed, needs authentication ou pending— (incluindo envolver o npx com cmd /c no Windows), veja como resolver os erros de conexão do MCP.
9. Permissões e ferramentas
A família do "pediu permissão mesmo em modo bypass". Dois pontos-chave: a documentação oficial lista as ações que continuam pedindo confirmação no modo bypass, e as regras deny bloqueiam em todos os modos, inclusive no bypass (as regras allow não têm efeito no bypass; veja Choose a permission mode na documentação oficial).
| Sintoma | Causa | Solução |
|---|---|---|
| Asked for permission even in bypass mode | Regras ask explícitas, ferramentas que exigem interação do usuário como AskUserQuestion e rm / rmdir em um caminho crítico como a raiz, sua pasta pessoal ou o diretório de trabalho (o que a documentação chama de circuit breaker) continuam pedindo confirmação no bypass. Gravações em caminhos protegidos como .git e .claude não pedem no bypass | Verifique e ajuste as regras ask em /permissions. As regras deny bloqueiam sem perguntar |
| Tool execution denied by PreToolUse hook | Um hook bloqueou com código de saída 2 | Verifique o hook em .claude/settings.json. Veja a saída com claude --debug |
Para entender por que o bypass ainda para, veja por que ele pede permissão mesmo em modo bypass; para um design seguro de permissões, veja modos de permissão e segurança.
10. Outros (thinking / imagem-PDF / IDE)
- thinking blocks cannot be modified (400): um bug conhecido em que os blocos de extended-thinking se corrompem no histórico. Esc duas vezes → /rewind, ou então uma nova sessão, e
claude update. Detalhes: erro 400 de thinking blocks. - court / uma tag <invoke> crua aparece e a ferramenta não executa: um bug conhecido em que a tag de controle da chamada de ferramenta é gerada quebrada. Se falhar duas vezes, inicie uma sessão nova (/clear). Detalhes: erro de vazamento da tag court / invoke explicado.
- Could not check the pull request status: um problema de conexão com o GitHub (muitas vezes autenticação do
gh). Comece comgh auth status. Detalhes: erro de status do PR. - Image was too large / PDF too large: imagens acima de 8000px no lado maior (2000px quando há muitas imagens no contexto), PDFs com mais de 100 páginas / 20 MB são rejeitados. Esc duas vezes para remover o anexo; redimensione ou leia por intervalo de linhas. Referencie arquivos grandes pelo caminho em vez de colar.
- A extensão do VS Code não conecta: confirme que
claude --versionfunciona no terminal do VS Code. Verifique o PATH, reinicie o VS Code, reinstale a extensão.
11. Guia rápido erro → solução
| Quando isto acontece | Tente isto primeiro |
|---|---|
| Causa desconhecida / geral | claude doctor → /status → /context |
| Pediu login de repente | /status → (se for uma chave antiga) unset ANTHROPIC_API_KEY → /login |
| Atingiu um limite de taxa | /usage → /model mais leve → /compact → espere |
| Prompt is too long | /compact → /clear → leia arquivos grandes por intervalo de linhas |
| 500/529/timeout | Verifique status.claude.com → espere um pouco → /model |
| command not found: claude | Adicione ~/.local/bin ao PATH |
| Não conecta (rede corporativa) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP não conecta | /mcp → verifique URL/permissões/comando → MCP_TIMEOUT |
| Pediu permissão mesmo em bypass | /permissions para verificar as regras ask (remover um caminho crítico pede confirmação mesmo no bypass) |
| Só quer que funcione | claude update (a versão mais recente corrige muita coisa) |
Resumo
O Claude Code tem muitos erros, mas o primeiro movimento é isolar a causa com três comandos: claude doctor / /status / /context — isso destrava a maioria dos problemas. Os mais comuns são quatro famílias — uso/limites de taxa, estouro de contexto, autenticação expirada, falha de conexão do MCP — com /usage, /compact, /login e /mcp como soluções de primeira linha.
E o movimento mais forte e facilmente esquecido é manter tudo atualizado com claude update. O Claude Code é atualizado rápido, e bugs antigos (como o 400 dos thinking blocks) muitas vezes desaparecem só com a atualização da versão. "Quando travar, os três comandos de diagnóstico primeiro; se não resolver, atualize para a versão mais recente." Mantenha esse padrão e você vai parar de derreter tempo em erros.
Se não for um erro, mas o que incomoda é o comportamento parecer pesado ou lento demais, revisar o ajuste de esforço (effort) do Claude Code permite calibrar o equilíbrio entre a profundidade do raciocínio e o consumo de tokens. Leitura relacionada: erro 400 de thinking blocks, erro de verificação de status do PR, economia de tokens no Claude Code, por que ele pede permissão em modo bypass, o que é MCP e The model returned no content: causas e solução.
FAQ
Q. Apareceu um erro — o que faço primeiro?
A. Rode claude doctor. Ele verifica instalação, configurações, MCP e contexto de uma só vez. Depois olhe /status (autenticação atual) e /context (o que está consumindo o contexto), e normalmente você já consegue dizer se é um problema de autenticação, contexto ou conexão.
Q. Atinjo os limites de taxa rápido. O que ajuda?
A. Cada turno do Claude Code carrega conteúdo de arquivos e chamadas de ferramentas, e a documentação oficial observa que uma única sessão de depuração pode consumir mais do que um dia de chat, então você os atinge antes do esperado. Verifique limites e horário de reset com /usage, mude para um modelo mais leve com /model, encolha o histórico com /compact e desative MCP não usados. Se não bastar, considere um plano superior (Max, etc.) ou créditos extras.
Q. Diz "Invalid API key", mas minha chave deveria estar correta.
A. A causa clássica é uma variável de ambiente ANTHROPIC_API_KEY antiga sobrepondo sua assinatura. Verifique com env | grep ANTHROPIC, unset ANTHROPIC_API_KEY (remova também do perfil do shell), depois /login e confirme com /status.
Q. Não conecta na minha rede corporativa.
A. Primeiro confirme a acessibilidade com curl -I https://api.anthropic.com. Para um proxy, defina HTTPS_PROXY; para inspeção TLS, aponte NODE_EXTRA_CA_CERTS para o certificado CA. Não use NODE_TLS_REJECT_UNAUTHORIZED=0 — é perigoso. O caminho correto é pedir ao TI para liberar api.anthropic.com.
Q. Nada do que tento funciona — último recurso?
A. Atualize para a versão mais recente com claude update. O Claude Code é atualizado rápido e bugs conhecidos muitas vezes desaparecem só com a atualização da versão. Se ainda falhar, reporte com /feedback (inclui o log da conversa) à Anthropic.
