Í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 válida (token expirado, etc.) | /login. Se repetir, verifique o relógio do sistema e o bloqueio do Keychain |
| Invalid API key | Uma ANTHROPIC_API_KEY antiga permanece | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | Logout em outro lugar / desativado pelo admin | /logout → /login. Suspeite também de relógio desalinhado |
| This organization has been disabled | Chave de API de uma org desativada sobrepõe | Remova a chave do perfil do shell (.zshrc etc.) → /login → confirme com /status |
| 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.
3. Uso e limites de taxa (o mais comum)
A reclamação mais comum com o Claude Code. O Claude Code consome de 10 a 100x os tokens do chat (conversas com múltiplos turnos, contextos enormes, idas e voltas de ferramentas), então você atinge os limites mais rápido do que parece que deveria.
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: "429 / Request rejected" é um excesso de taxa na sua chave de API ou workspace. "Credit balance is too low" é o saldo pré-pago do Console esgotado (recarregue no billing ou mude para uma assinatura). Note que, por volta de março de 2026, usuários Max relataram que suas janelas de 5 horas drenavam excepcionalmente rápido na imprensa técnica e nas issues do repositório oficial (suspeita de bug). 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.
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 |
| Auto-compact 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.
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 |
| model not found / no access | Nome de modelo errado ou fora do seu plano | /model para reselecionar. Verifique uma ANTHROPIC_MODEL antiga na env var |
| Opus is not available with Pro plan | Modelo selecionado fora do seu plano | /model para um disponível. Após mudar de plano, /logout→/login |
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 |
| Multiple claude installations found | Duplicatas de npm/Homebrew/native | Mantenha uma, 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) |
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 / ECONNREFUSED / ETIMEDOUT | 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 |
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 | Inicialização >5s, etc. | MCP_TIMEOUT=10000 claude (ms). Por servidor: "timeout" em .mcp.json |
9. Permissões e ferramentas
A família do "pediu permissão mesmo em modo bypass". O ponto-chave: as regras deny têm precedência sobre allow e bypass.
| Sintoma | Causa | Solução |
|---|---|---|
| Asked for permission even in bypass mode | As regras deny vencem; operações perigosas sempre pedem confirmação (circuit breaker) | Verifique e ajuste as regras deny em /permissions |
| 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. - 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, PDFs com mais de 100 páginas / 32 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 deny |
| 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.
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 e o que é MCP.
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. O Claude Code consome de 10 a 100x os tokens do 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.
