Continue usando o Claude Code e uma hora você vai travar. Este capítulo não é um dicionário de erros. Ele existe para lhe dar uma ordem de triagem que desce do sintoma até a causa.
Com essa ordem em mãos, você consegue encaixar na categoria certa até uma mensagem de erro que nunca viu. O artigo sobre a correção específica é o que você lê depois.
O que fazer antes de pesquisar a mensagem de erro
Quando as pessoas travam, a maioria cola a mensagem de erro direto na busca. Funciona, mas quase sempre três conferências antes levam você lá mais rápido.
Se estava, a causa não é o ambiente, e sim o que mudou logo antes. Uma conversa que ficou longa, uma configuração que você acrescentou, uma rede para a qual você trocou.
Toda vez significa uma configuração ou o ambiente. De vez em quando significa congestionamento ou a sua conexão, e muitas vezes a causa nem está do seu lado.
Na inicialização, no momento em que você enviou a instrução ou no meio da resposta? Onde ele parou quase define a categoria.
O CHECK 3 é o que mais trabalha. Assim que você sabe em que ponto do loop coletar → agir → verificar do capítulo 1 ele parou, os candidatos se estreitam rápido.
Encaixar o problema em uma de cinco categorias
Os erros do Claude Code se dividem em cinco grupos, conforme o lugar onde está a causa. Decida primeiro em qual deles você está.
Ele inicia?
Não → problema do próprio aplicativo (veja o extra abaixo)
Sim
↓
Você consegue enviar uma instrução?
Não, ele recusa → 1. Autenticação
Sim
↓
Uma resposta volta?
Não, nada chega / é cortada → 2. Conexão
Ele diz "limite" → 3. Limites de uso
Ele diz "longo demais" → 4. Contexto
Sim
↓
Falha sempre que entra uma ferramenta externa → 5. Ferramentas e extensões
Use essa ramificação para fazer a sua aposta e depois vá à seção correspondente abaixo. Cada categoria tem o próprio formato de correção, então misturá-las é o jeito de perder uma tarde.
1. Autenticação — ele não aceita quem você é
O sintoma é ouvir que você não está logado, ou ser recusado porque as suas credenciais são inválidas. O sinal característico é que ele para antes de a sua instrução ir a qualquer lugar.
Uma sessão expirada / estar logado com outra conta / confundir uma chave de API com uma assinatura / uma rede corporativa bloqueando o tráfego de autenticação
Entrar de novo → conferir com qual conta você está logado → tentar outra conexão (o roteamento pelo celular, por exemplo). Se a terceira resolver, você está na categoria 2
Como entrar de novo resolve essa categoria com muita frequência, ela também é a categoria em que as pessoas insistem em cavar quando não resolve. Tente duas vezes e, se continuar quebrado, suspeite da categoria 2. O tráfego de autenticação também passa pela rede.
2. Conexão — nada chega, ou é cortado
Esta é a categoria mais mal interpretada. Não é necessariamente a sua configuração que está errada.
Os sintomas se dividem em três.
Um proxy, o TLS ou uma rede corporativa fechando o caminho. É um problema de ambiente, e outra conexão isola o caso.
O serviço está cheio. Esperar é a resposta certa, e mexer nas configurações deixa só efeitos colaterais.
A conexão cai no meio de uma resposta longa. Quebrar a saída em pedaços mais curtos às vezes faz o problema parar de acontecer.
Cada um tem o próprio artigo: resolver erros de rede, proxy e TLS, erros 529 Overloaded e 500 e Connection closed mid-response.
Não tente resolver congestionamento com configuração. Se você mudar dez configurações tentando reproduzir algo que só falha de vez em quando, nunca vai saber se quem resolveu foi você ou o tempo. Espere um pouco e tente de novo primeiro, e descubra se acontece toda vez.
3. Limites de uso — você gastou a cota
Esta é a categoria em que ele avisa que você bateu em um limite. Não é um erro, é o desenho do produto, então o que você corrige é o jeito de usar, não uma configuração.
O que é preciso entender aqui é que há mais de uma cota. Uma cota de ciclo mais curto e uma de ciclo mais longo existem separadamente. Uma pode se recuperar enquanto a outra segue gasta, e você continua bloqueado. "Voltou faz pouco e agora parou de novo" costuma ser isso.
Os detalhes estão em como lidar com o usage limit reached e, para a cota semanal medida na prática, em a verdade sobre o limite semanal resetar antes. Reduzir o próprio consumo é o capítulo 7.
4. Contexto — a entrada é longa demais
Esta é a categoria em que você é recusado por ser longo demais. Pense nela como a conversa sobre a janela de contexto do capítulo 1 aparecendo em forma de sintoma.
Dobre o histórico, ou corte e recomece. Dobrar em uma pausa do trabalho é o padrão.
Não cole um arquivo ou um log enorme por inteiro. Entregue só a parte relevante, ou deixe que ele vá procurar.
A correção do sintoma está em Prompt is too long: causas e soluções, e o julgamento sobre quando dobrar está em Devo rodar o /compact em intervalos fixos?.
Note que a saída também pode ser interrompida por violar uma política. Isso não é um problema de tamanho, então não confunda os dois. É outro tipo de coisa.
5. Ferramentas e extensões — o que você plugou não funciona
Esta é a categoria que aparece depois que você acrescenta um servidor MCP ou uma ferramenta externa. A triagem é fácil: veja se remover resolve.
Desligue todas as extensões
→ resolveu : as extensões são a causa. Recoloque uma por vez para achar a culpada
→ não resolveu : as extensões não têm relação. Volte para 1-4
Quando você souber que uma extensão é a causa, vá para erros de conexão de MCP: causas e soluções. Quase sempre é o formato da configuração, o caminho no comando de inicialização ou as permissões.
O que você não deve fazer aqui é duvidar da inteligência do Claude. Se uma extensão não está conectada, o Claude se comporta como se aquela ferramenta não existisse. "Eu mandei e ele não faz" acabar sendo um problema de conexão é uma história comum.
Um extra — o aplicativo em si não abre
Se você usa o aplicativo de desktop em vez da versão de terminal, ele pode parar antes mesmo de chegar ao Claude Code. Isso não é nenhuma das cinco categorias, então fica fora da tabela de triagem.
O caso que exige reparo no Windows está em Não é possível abrir este aplicativo: reparando o Claude Desktop no Windows, e o caso que congela por causa da renderização está em por que o GPU process gone congela tudo e o que fazer.
Cinco movimentos para quando você continua travado
Para quando você não consegue dizer a categoria, ou consegue e mesmo assim não resolve. Tente estes de cima para baixo. Estão ordenados do mais barato ao mais caro.
Problemas vindos do contexto somem com isto. O movimento mais barato que existe.
Congestionamento e limites se resolvem só com isto. Não mexa nas configurações.
Se isto resolver, a causa fica confirmada como a rede do seu lado.
A triagem da categoria 5. Recoloque uma por vez. Todas de uma vez não diz nada.
Tente a mesma coisa em um diretório vazio. Se não reproduzir, a causa está no projeto.
Mude uma coisa de cada vez. Estar travado dá vontade de mudar várias coisas ao mesmo tempo, mas aí você acaba sem nunca saber qual delas funcionou, e da próxima vez que o mesmo sintoma aparecer você recomeça do zero. Cravar o único movimento que funcionou é muitíssimo mais barato no longo prazo.
Se você preferir pesquisar pela própria mensagem de erro, erros comuns e como resolver funciona como índice.
Resumo
- Antes de pesquisar a mensagem de erro, confira três coisas: estava funcionando um minuto atrás, acontece toda vez e onde ele parou
- As causas caem em cinco categorias: autenticação, conexão, limites de uso, contexto e ferramentas. Não misture as categorias durante os testes
- Para congestionamento e limites, esperar é a resposta certa. Mexer nas configurações não deixa nada além de efeitos colaterais
- Há mais de uma cota. Um ciclo mais curto e um ciclo mais longo correm separados, então ele pode voltar e parar de novo
- A categoria de ferramentas se tria de uma vez pela pergunta "remover tudo resolve?". Recoloque uma por vez
- Quando você travar, cinco movimentos em ordem de custo. E mude uma coisa de cada vez
Depois de aprender a se destravar, o próximo trabalho é decidir até onde delegar. Siga para o capítulo 5, "Permissões e segurança".