Índice
- 1. O que a mensagem realmente significa: a definição oficial
- 2. O que fazer primeiro: nada foi perdido
- 3. Por que cai: as três camadas onde a conexão fecha
- 4. O que as capturas de pacotes mostraram: um fechamento do servidor
- 5. Verifique sua versão: a cronologia das correções
- 6. Condições que aumentam a probabilidade
- 7. Resolver agora: checklist para usuários
- 8. Para desenvolvedores: como evitar na API/SDK
- 9. Como diferenciar de erros parecidos
- 10. Situação oficial e o que continua sem confirmação
- Perguntas frequentes
Você está trabalhando no Claude Code e, no meio de uma resposta, tudo para com isto:
API Error: Connection closed mid-response. The response above may be incomplete.
Pode acontecer enquanto um relatório longo está sendo escrito, enquanto vários arquivos estão sendo lidos ou logo depois de abrir uma sessão nova. O momento varia e não há como reproduzir de forma confiável. Isso não é um problema de como você escreveu o prompt: é um evento da camada de transporte, porque a conexão que carregava a resposta em streaming foi fechada enquanto a resposta ainda chegava.
E existe um dado que pesa mais do que qualquer teoria. A maior parte dos relatos públicos desse erro vem de versões anteriores à mudança do Claude Code na forma de lidar com conexões caídas. Ao acompanhar o changelog oficial, você encontra cinco correções distintas de conexão e retentativa a partir da 2.1.179. Este artigo se baseia apenas na referência de erros oficial, no changelog oficial e em relatos apoiados por capturas de pacotes, e cobre (1) o que a mensagem significa com precisão, (2) o que fazer agora, (3) onde a conexão está realmente fechando, (4) o que mudou entre versões e (5) como se proteger como desenvolvedor.
Tudo o que já foi transmitido está intacto. A forma documentada de retomar é responder continue.
A 2.1.198 impediu que quedas breves de rede matassem o turno; a 2.1.214 impediu que as retentativas reutilizassem uma conexão morta.
Sua máquina, o caminho (proxy/VPN) ou o lado do servidor: cada um exige uma resposta diferente. Há relatos de fechamentos iniciados pelo servidor.
1. O que a mensagem realmente significa: a definição oficial
Primeiro: este texto é um aviso que o próprio Claude Code escreve, não uma resposta de erro devolvida pela API. A referência de erros oficial do Claude Code explica assim toda a família de mensagens terminadas em "The response above may be incomplete.": quando uma resposta em streaming falha depois que Claude já produziu saída visível, reenviar a requisição poderia executar duas vezes as mesmas chamadas de ferramenta, então o Claude Code mantém o que já foi transmitido e acrescenta este aviso em vez de descartar o turno.
O final da frase é, portanto, o nome da causa. A referência lista três variantes.
A explicação oficial cabe em uma linha: a conexão caiu. O stream estava funcionando, mas a conexão que o carregava fechou.
Oficialmente: o stream parou de enviar dados. A conexão continua viva, mas fica em silêncio. Não é corte: é parada.
Um erro de sobrecarga ou 5xx no meio do stream. Segundo a documentação, essa variante exige a v2.1.199 ou posterior; antes disso a saída parcial era descartada e o turno inteiro reportado como erro.
As três em uma linha. Connection closed significa que o enlace foi cortado; Response stalled, que ficou em silêncio; Server error, que o servidor caiu. Todas parecem "parou no meio", mas cada uma aconteceu em um ponto diferente do transporte.
A referência ainda deixa claro outro comportamento que vale conhecer. Se a mesma falha acontece antes de qualquer saída visível, o Claude Code repete a requisição em vez de encerrar o turno. Ou seja: o fato de você estar lendo esta mensagem significa que já havia saída na tela — logo, reenviar poderia duplicar efeitos colaterais, e o Claude Code deliberadamente não tentou de novo. Ver o erro não quer dizer que nada foi tentado.
2. O que fazer primeiro: nada foi perdido
Antes de entrar em pânico e repetir a mesma instrução, siga esta ordem.
Como diz a documentação, nada foi perdido. O que falta costuma ser só as últimas frases ou a última chamada de ferramenta.
continueÉ o passo de recuperação citado na referência oficial. Faça Claude seguir de onde parou, em vez de recomeçar.
Se caiu durante edições de arquivos ou execução de comandos, parte pode já ter rodado. Veja o estado real com git status antes de continuar.
Se aparecer várias vezes na mesma sessão, confira a versão antes de qualquer outra coisa. Essa área já foi corrigida várias vezes.
Não pule o passo 3. Quando a documentação diz que reenviar "poderia executar duas vezes as mesmas chamadas de ferramenta", o outro lado é que algumas ferramentas talvez já tenham rodado no momento da queda. Se aconteceu no meio de escrever arquivos, fazer commit ou publicar, olhar o estado real primeiro é o caminho mais rápido de volta.
3. Por que cai: as três camadas onde a conexão fecha
"A conexão caiu" sozinho não ajuda, então convém separar os lugares de onde o fechamento pode partir. Os relatos se agrupam em três camadas.
Uma oscilação de Wi-Fi, uma troca de célula no celular, sair da suspensão. O changelog oficial até corrige "requisições de streaming que falham depois que a máquina acorda" (2.1.186), então essa camada é real.
O que ajuda: cabo ou enlace estável; não deixar a máquina dormir em tarefas longas.
A documentação oficial de erros da API da Claude afirma que algumas redes derrubam conexões ociosas após um período variável e recomenda configurar keep-alive de TCP. Proxies corporativos e VPNs são propensos exatamente a isso.
O que ajuda: contornar o proxy/VPN por um momento e ver se ainda reproduz.
Existe evidência em nível de pacote de que a conexão é fechada do lado do servidor com o stream em curso (próxima seção). Nada que você arrume localmente evita isso.
O que ajuda: o comportamento de retentativa do cliente — e é por isso que atualizar funciona.
De fato, quem abriu a issue #69415 do GitHub ([BUG] API Error: Connection closed mid-response ==> frequent enough to make Claude Code unusable for any task, criada em 18 de junho de 2026 e ainda aberta na data deste texto) descreve Windows 11 com WSL2, conexão direta sem firewall corporativo e sem proxy, no Claude Code 2.1.181. Ou seja, a alegação é de que acontece mesmo descartando as camadas 1 e 2. A issue tem as etiquetas area:networking, platform:vscode e platform:wsl.
A mesma pessoa escreve que, na mesma máquina e na mesma rede, outros assistentes de IA (GitHub Copilot, Cursor e outros) concluem a mesma tarefa. Isso, porém, é uma comparação feita por um usuário — não uma determinação de causa pela Anthropic, e vale manter a distinção.
Outro relato descreve condições claramente diferentes. A issue #69336 (occurs immediately in new context window, criada em 18 de junho de 2026 e aberta, Claude Code 2.1.173, Debian 13, um Claude Agent SDK auto-hospedado) informa que a frequência sobe depois que o resumo de contexto (compact) roda. Ela carrega area:agent-sdk, area:api e platform:linux, e abrir uma conversa totalmente nova é descrito como contorno temporário. A issue #69517 (no Claude Cowork, 19 de junho de 2026, macOS, 2.1.183) foi fechada como duplicada.
4. O que as capturas de pacotes mostraram: um fechamento do servidor
A investigação de primeira mão mais aprofundada sobre essa classe de erro é a issue #67766 (criada em 12 de junho de 2026, ainda aberta). Quem a reportou capturou pacotes no próprio ambiente e correlacionou dez incidentes.
Fonte: as capturas de pacotes e transcrições publicadas por quem reportou a issue #67766 do GitHub. São medições de um único usuário, não resultados verificados pela Anthropic.
O detalhe tecnicamente revelador é que os fechamentos eram seletivos. Segundo o relato, outras conexões para o mesmo destino continuaram vivas durante o evento, e a que foi fechada era a conexão pertencente ao processo que fazia a requisição. As conexões de outros dois processos claude em execução simultânea ficaram intactas. Uma queda de enlace teria levado todas junto; não foi o caso.
Ele também observou que em quatro dos dez incidentes lotes de fechamentos atingiram várias conexões do pool ao mesmo tempo, e que três dispararam no segundo :54 de minutos próximos (01:19:54, 01:20:54 e 01:22:54 UTC), o que interpreta como sinal de algo rodando em ciclo de 60 segundos.
🟡 Quanta confiança esta seção merece?
A mensagem exibida na issue #67766 é "API Error: The socket connection was closed unexpectedly", com redação diferente da deste artigo. Não dá para afirmar que sejam o mesmo defeito. Dito isso, hoje é a única evidência pública em nível de pacote sobre o mesmo tipo de comportamento — uma conexão que fecha com um stream em curso —, o que a torna útil como hipótese de trabalho. Vale acrescentar que a Anthropic não publicou nenhuma explicação sobre esse relato até esta data.
5. Verifique sua versão: a cronologia das correções
Esta é a parte mais útil na prática. Ao acompanhar o changelog oficial do Claude Code, você vê que o tratamento de quedas de conexão no meio do stream foi melhorado várias vezes. Cada entrada abaixo está de fato no changelog.
Respostas parciais passaram a ser preservadas quando a conexão cai no meio do stream. Antes disso vinha um erro cru, e o indicador podia travar em "running tool".
O aviso de estagnação passou a ser "Waiting for API response · will retry in …" e agora dispara após 20 segundos de silêncio, em vez de 10, então oscilações curtas não geram mais alerta.
Corrigido o caso em que quedas breves de rede no meio da resposta abortavam o turno. Erros transitórios como ECONNRESET agora são repetidos com backoff em vez de falhar.
Corrigido o descarte de respostas em streaming quando um erro de sobrecarga ou de servidor chega no meio do stream. A parte parcial agora é mantida com um aviso de resposta incompleta — daí vem a variante Server error mid-response.
O pool de conexões keep-alive agora é desativado após um erro de conexão obsoleta, de modo que as retentativas abram um socket novo. Isso fala diretamente ao padrão descrito na #67766: uma conexão reaproveitada sendo fechada.
Agora compare essa cronologia com as versões dos relatos citados acima.
| Relato | Versão na época | Correções ainda não aplicadas |
|---|---|---|
| #69336 | 2.1.173 | Todas: 2.1.179 / 198 / 199 / 214 |
| #69415 | 2.1.181 | 2.1.198 / 199 / 214 (a melhoria de retentativa e a correção do pool) |
| #69517 | 2.1.183 | 2.1.198 / 199 / 214 |
Os três são anteriores à 2.1.198, a versão que absorve quedas transitórias com retentativas. Portanto, a primeira coisa a checar é a sua própria versão.
claude --versionSe for menor que 2.1.198, atualizar rende mais do que investigar. A entrada mais recente do changelog nesta data é a 2.1.220, que inclui todas as correções acima.
Dito isso, atualizar não garante que o erro suma. O changelog não tem nenhuma entrada que cite "Connection closed" em si; tudo acima são melhorias no tratamento de conexão adjacente. Encare a atualização como a primeira medida de melhor custo-benefício, não como cura comprovada.
6. Condições que aumentam a probabilidade
Estes fatores se repetem nos relatos.
Ler vários arquivos grandes e produzir um relatório estruturado — qualquer coisa que mantenha o stream aberto por muito tempo (#69415).
Há relato de que a frequência sobe depois que o resumo de contexto roda (#69336). Após um resumo, as requisições tendem a ficar maiores.
Nas medições da #67766, as conexões fechadas carregavam corpos de requisição de 1 a 2,5 MB. Para referência, o limite oficial da Messages API é de 32 MB.
Proxies corporativos, VPNs, enlaces de longa distância. É a camada que a documentação oficial descreve ao falar de redes que derrubam conexões ociosas.
O changelog 2.1.186 corrigiu requisições de streaming que falhavam depois que a máquina acordava. Não deixe a máquina dormir em tarefas longas.
Na #67766, 87 de 171 incidentes ocorreram menos de cinco segundos após a chamada anterior — um padrão que cortes por inatividade sozinhos não explicam.
7. Resolver agora: checklist para usuários
Vá descendo a lista; o mais barato vem primeiro.
| # | O que fazer | Para quê |
|---|---|---|
| 1 | Responder continue | O passo de recuperação documentado. Reaproveita o que já chegou em vez de recomeçar. |
| 2 | Rodar claude --version e atualizar se estiver antigo | Traz a melhoria de retentativa da 2.1.198 e a correção de pool da 2.1.214. Faça isso primeiro. |
| 3 | Verificar efeitos colaterais (git status e afins) | Ver se alguma ferramenta rodou parcialmente antes da queda. Evita execução duplicada. |
| 4 | Dividir a tarefa | Respostas mais curtas significam menos tempo exposto. Quebre "leia todos os arquivos e escreva o relatório" em etapas. |
| 5 | Contornar o proxy/VPN por um tempo e testar de novo | Isola a camada 2. Se parar, o caminho é o culpado. |
| 6 | Desativar suspensão e economia de energia; usar cabo | Isola a camada 1 — especialmente em notebooks rodando tarefas longas. |
| 7 | Testar em uma sessão totalmente nova | O contorno temporário relatado na #69336. Às vezes funciona quando o erro dispara logo após um resumo. |
| 8 | Se reproduzir, reportar com detalhes | Como orienta a documentação oficial da API, inclua o request_id (o identificador que começa com req_) para acelerar a investigação. |
O que não fazer. Desativar a verificação TLS (NODE_TLS_REJECT_UNAUTHORIZED=0 e afins) porque "a conexão fica caindo" ataca um sintoma completamente diferente e joga fora a segurança do seu tráfego. Erros de certificado são outro erro, com outra solução.
8. Para desenvolvedores: como evitar na API/SDK
Se você enfrenta a mesma classe de queda pelo Claude Agent SDK ou pela sua própria integração com a API, a documentação oficial de erros da API da Claude dá diretrizes concretas de projeto.
A documentação recomenda a Messages API em streaming ou a Message Batches API para requisições longas, sobretudo acima de 10 minutos. Um max_tokens alto sem streaming é o formato com maior chance de ser cortado.
A documentação afirma que configurar keep-alive de TCP reduz o impacto de timeouts por inatividade se você escreve uma integração direta. Os SDKs oficiais já fazem isso. Confira se você montou seu próprio cliente HTTP.
Os SDKs oficiais repetem falhas transitórias — erros de conexão, limites de taxa, 5xx — duas vezes por padrão, com backoff exponencial e respeitando o cabeçalho retry-after. Uma opção do cliente permite mudar ou desativar.
A armadilha que a documentação aponta explicitamente: com SSE, um erro pode ocorrer depois que a API já devolveu 200, então ele não segue o caminho padrão de erros HTTP. Trate os eventos de erro no meio do stream à parte.
O próprio Claude Code seguiu esse caminho na 2.1.179 e na 2.1.199. Guardar os blocos recebidos e pedir o restante custa menos — em tokens e em efeitos colaterais — do que descartar tudo e reenviar.
Na 2.1.214, o Claude Code passou a desativar o pool keep-alive após um erro de conexão obsoleta, para que as retentativas abram um socket novo. Vale checar se a sua retentativa está pegando a mesma conexão morta.
Para cargas em que você prefere não pressupor uma conexão ininterrupta — processamento em lote é o caso óbvio —, o caminho recomendado oficialmente é a Message Batches API, buscando os resultados por polling. Isso elimina o risco de rede na estrutura, em vez de apenas mitigá-lo.
9. Como diferenciar de erros parecidos
Os erros de transporte do Claude Code se parecem muito. A forma mais rápida de separá-los é pelo quanto a requisição avançou.
| Mensagem | Onde parou | Resposta principal |
|---|---|---|
| Connection closed mid-response (este artigo) | Conectado e transmitindo, e então cortado | continue / atualizar / isolar o caminho |
| Response stalled mid-stream | Conexão viva, mas em silêncio | Tratado à parte (atenção ao encadeamento com o loop de repetição) |
| Server error mid-response | Um erro 5xx ou de sobrecarga no meio do stream | Esperar e repetir. Veja o artigo sobre 529/500 |
| Unable to connect / SSL certificate verification failed | Nunca chegou a conectar | Proxy, CA corporativa, firewall. Veja o artigo sobre erros de conexão |
| Prompt is too long | Rejeitado antes do envio (a rede está bem) | Reduzir o contexto. Veja o artigo dedicado |
A maior bifurcação é simplesmente se apareceu alguma resposta na tela. Se não veio nem um caractere, desconfie da conexão em si: configuração e caminho. Se a saída apareceu e depois parou, isso prova que a conexão funcionava — então pare de mexer nas configurações e siga os passos de isolamento deste artigo.
10. Situação oficial e o que continua sem confirmação
Para evitar confusão, eis o que pode ser confirmado oficialmente e o que não.
- A mensagem está formalmente documentada na referência de erros oficial e significa "a conexão caiu"
- A saída já transmitida é preservada — por projeto
- O passo de recuperação é responder
continue - Falhas anteriores a qualquer saída visível são repetidas automaticamente
- Correções de tratamento de conexão saíram na 2.1.179 / 198 / 199 / 214
- Servidores enviando um FIN no meio do stream (medido na #67766 — mas sob outra mensagem)
- O envolvimento de uma varredura de 60 segundos (inferência de quem reportou)
- Picos logo após um compact (#69336)
- Outros assistentes de IA não falharem nas mesmas condições (comparação de quem reportou a #69415)
- Uma explicação oficial da causa pela Anthropic (sem resposta pública na #69415, #69336 ou #67766)
- Uma entrada de correção que cite "Connection closed" (essa expressão não aparece no changelog)
- #69415, #69336 e #67766 continuam todas abertas
Em resumo: o sintoma e a resposta estão documentados oficialmente, mas nenhuma explicação oficial de por que cai foi publicada. Nesse cenário, os hábitos operacionais vencem a caça à causa raiz: mantenha os turnos curtos, verifique o estado à medida que avança em operações com efeitos colaterais e permaneça em uma versão atual.
Perguntas frequentes
Q1. Quando aparece "Connection closed mid-response", a saída até ali é perdida?
Não. Como a referência de erros oficial deixa explícito, tudo o que já foi transmitido é mantido. O Claude Code acrescenta o aviso de propósito em vez de reenviar, porque reenviar poderia executar duas vezes as mesmas chamadas de ferramenta. O que falta costuma ser apenas as últimas frases ou a última chamada de ferramenta.
Q2. O que devo responder para retomar de onde parou?
Responda continue. É o passo de recuperação citado na referência de erros oficial. Repetir a instrução original arrisca duplicar operações que já rodaram.
Q3. Os tokens são desperdiçados?
O que foi gerado até a queda já foi consumido. Quem reportou a issue #69336 observa que os tokens consumidos não são devolvidos. É exatamente por isso que usar continue — em vez de recomeçar — importa tanto em custo quanto em tempo.
Q4. É a mesma coisa que "Response stalled mid-stream"?
Não. Pelas definições oficiais, Connection closed significa "a conexão caiu" e Response stalled significa "o stream parou de enviar dados": cortado versus silencioso. Na tela parecem iguais, mas a variante stalled foi relatada em conjunto com um loop de repetição do modelo, e a solução é outra. Veja o artigo sobre Response stalled mid-stream.
Q5. A culpa é da minha rede?
Pode ser, mas não necessariamente. Quem reportou a issue #69415 viu o erro em conexão direta, sem proxy nem firewall, e as capturas de pacotes da issue #67766 indicam que o fechamento partiu do servidor. Contorne primeiro qualquer proxy ou VPN e veja se ainda reproduz; se nada mudar, não é um problema puramente local.
Q6. Atualizar o Claude Code resolve?
É a primeira coisa de maior retorno a tentar. O changelog oficial mostra a 2.1.198 corrigindo "quedas breves de rede no meio da resposta que abortavam o turno", e a 2.1.214 mudando o pool keep-alive para desativá-lo após um erro de conexão obsoleta, de modo que as retentativas abram um socket novo. O grosso dos relatos (2.1.173 a 2.1.183) é anterior a isso. Mas, como nenhuma entrada do changelog cita "Connection closed" em si, atualizar é uma melhoria provável, não uma cura garantida.
Q7. Acontece o tempo todo em tarefas longas. Existe algum contorno?
Dividir a tarefa para que cada resposta fique mais curta é a opção mais confiável. Trabalhos em bloco do tipo "leia todos os arquivos grandes e escreva o relatório" expõem o stream por muito tempo; separar a leitura da escrita encurta essa janela e reduz a chance de esbarrar em uma queda. A issue #69336 também relata que abrir uma conversa nova ajudou temporariamente.
Q8. Como desenvolvedor, como evito isso no meu app?
As diretrizes da documentação oficial da API da Claude são claras: (1) sempre use streaming em respostas longas e considere a Batches API acima de 10 minutos; (2) configure keep-alive de TCP (os SDKs oficiais já fazem); (3) com SSE, erros podem chegar depois de um 200, então trate os eventos de erro no meio do stream à parte; (4) em uma queda, guarde o que recebeu e peça o restante. Inclua o request_id ao contatar o suporte.
Q9. Recebo o mesmo erro no Claude Cowork e no Agent SDK.
A mesma mensagem foi relatada nesses contextos. A issue #69517 reporta no Claude Cowork (fechada como duplicada) e a #69336 por meio de um Claude Agent SDK auto-hospedado. É um comportamento da camada que lida com respostas em streaming, então a abordagem é a mesma: retomar em vez de reiniciar, manter-se em uma versão atual e projetar bem as retentativas.
Artigos relacionados
- Claude Code: loop infinito de "court" e "Response stalled mid-stream" — causas e soluções
- Claude Code: erro de conexão de rede, proxy e certificado TLS
- Claude Code 529 Overloaded / 500: o que significa e como resolver
- Erro "Prompt is too long" no Claude Code: causas e soluções
- Erros Comuns do Claude Code e Como Resolver — A Referência Completa
