Contenido
- 1. Qué significa exactamente el mensaje: la definición oficial
- 2. Lo primero que debes hacer: no has perdido nada
- 3. Por qué se corta: las tres capas donde se cierra la conexión
- 4. Lo que mostraron las capturas de paquetes: un cierre del servidor
- 5. Comprueba tu versión: la cronología de las correcciones
- 6. Condiciones que aumentan la probabilidad
- 7. Solucionarlo ya: lista de comprobación
- 8. Para desarrolladores: cómo evitarlo desde la API/SDK
- 9. Cómo distinguirlo de errores parecidos
- 10. Estado oficial y lo que sigue sin confirmarse
- Preguntas frecuentes
Estás trabajando en Claude Code y, a mitad de una respuesta, todo se detiene con esto:
API Error: Connection closed mid-response. The response above may be incomplete.
Puede aparecer mientras se redacta un informe largo, mientras se leen varios archivos o justo después de abrir una sesión nueva. El momento varía y no hay forma fiable de reproducirlo. No es un problema de cómo escribiste el prompt: es un evento de la capa de transporte, porque la conexión que transportaba la respuesta en streaming se cerró mientras la respuesta todavía llegaba.
Y hay un dato que importa más que cualquier teoría. La mayoría de los informes públicos de este error provienen de versiones anteriores a que Claude Code cambiara su forma de gestionar las conexiones caídas. Si sigues el changelog oficial, encontrarás cinco correcciones distintas de conexión y reintentos a partir de la 2.1.179. Este artículo se apoya únicamente en la referencia de errores oficial, el changelog oficial y reportes respaldados por capturas de paquetes, y cubre (1) qué significa el mensaje con precisión, (2) qué hacer ahora mismo, (3) dónde se está cerrando realmente la conexión, (4) qué cambió entre versiones y (5) cómo protegerte como desarrollador.
Todo lo que ya se transmitió está intacto. La forma documentada de retomarlo es responder continue.
La 2.1.198 evitó que los cortes breves de red mataran el turno; la 2.1.214 evitó que los reintentos reutilizaran una conexión muerta.
Tu equipo, la ruta (proxy/VPN) o el lado del servidor: cada una exige una respuesta distinta. Se han reportado cierres iniciados por el servidor.
1. Qué significa exactamente el mensaje: la definición oficial
Lo primero: este texto es un aviso que escribe el propio Claude Code, no una respuesta de error devuelta por la API. La referencia de errores oficial de Claude Code explica así toda la familia de mensajes que terminan en «The response above may be incomplete.»: cuando una respuesta en streaming falla después de que Claude ya haya producido salida visible, reenviar la petición podría ejecutar dos veces las mismas llamadas a herramientas, así que Claude Code conserva lo que ya se transmitió y añade este aviso en lugar de descartar el turno.
El final de la frase es entonces el nombre de la causa. La referencia enumera tres variantes.
La explicación oficial cabe en una línea: la conexión se cayó. El stream funcionaba, pero la conexión que lo transportaba se cerró.
Oficialmente: el stream dejó de enviar datos. La conexión sigue viva pero se queda en silencio. No se corta: se detiene.
Un error de sobrecarga o 5xx a mitad del stream. Según la documentación, esta variante requiere la v2.1.199 o posterior; antes se descartaba la salida parcial y todo el turno se reportaba como error.
Las tres en una línea. Connection closed significa que el enlace se cortó; Response stalled, que se quedó en silencio; Server error, que el servidor se cayó. Todas parecen «se paró a mitad», pero cada una ocurrió en un punto distinto del transporte.
La referencia detalla además otro comportamiento que conviene conocer. Si el mismo fallo ocurre antes de que aparezca salida visible, Claude Code reintenta la petición en lugar de darla por terminada. Dicho de otro modo: que estés leyendo este mensaje significa que ya había salida en pantalla, así que reenviar podría duplicar efectos secundarios y Claude Code decidió deliberadamente no reintentar. Ver el error no significa que no se haya intentado nada.
2. Lo primero que debes hacer: no has perdido nada
Antes de entrar en pánico y repetir la misma instrucción, sigue este orden.
Como dice la documentación, no se ha perdido nada. Lo que falta suele ser solo las últimas frases o la última llamada a una herramienta.
continueEs el paso de recuperación que nombra la referencia oficial. Haz que Claude siga desde donde se detuvo, en vez de empezar de cero.
Si se cortó durante ediciones de archivos o ejecución de comandos, parte puede haberse ejecutado ya. Mira el estado real con git status antes de continuar.
Si sale varias veces en una sesión, comprueba la versión antes que nada. Esta área se ha corregido varias veces.
No te saltes el paso 3. Cuando la documentación dice que reenviar «podría ejecutar dos veces las mismas llamadas a herramientas», la otra cara es que algunas herramientas quizá ya se ejecutaron en el momento del corte. Si ocurrió a medias de escribir archivos, hacer commit o desplegar, mirar el estado real primero es el camino más rápido de vuelta.
3. Por qué se corta: las tres capas donde se cierra la conexión
«La conexión se cayó» no sirve de mucho por sí solo, así que conviene separar los sitios desde donde puede originarse el cierre. Los reportes se agrupan en tres capas.
Un microcorte de wifi, un cambio de celda en móvil, salir de suspensión. El changelog oficial incluso corrige «peticiones de streaming que fallan tras despertar la máquina» (2.1.186), así que esta capa es real.
Qué ayuda: cable o enlace estable; que el equipo no se suspenda en trabajos largos.
La documentación oficial de errores de la API de Claude indica que algunas redes cortan las conexiones inactivas tras un tiempo variable y recomienda configurar keep-alive de TCP. Los proxies corporativos y las VPN son propensos justo a eso.
Qué ayuda: saltarte el proxy o la VPN un momento y ver si se reproduce.
Existe evidencia a nivel de paquetes de que la conexión se cierra desde el servidor con el stream en vuelo (siguiente sección). Nada de lo que ordenes en local lo evita.
Qué ayuda: el comportamiento de reintento del cliente, y por eso actualizar funciona.
De hecho, quien reportó el issue #69415 de GitHub ([BUG] API Error: Connection closed mid-response ==> frequent enough to make Claude Code unusable for any task, abierto el 18 de junio de 2026 y todavía abierto al escribir esto) describe Windows 11 con WSL2, conexión directa sin cortafuegos corporativo ni proxy, en Claude Code 2.1.181. Es decir, sostiene que ocurre incluso descartando las capas 1 y 2. El issue lleva las etiquetas area:networking, platform:vscode y platform:wsl.
La misma persona escribe que, en la misma máquina y la misma red, otros asistentes de IA (GitHub Copilot, Cursor y otros) completan la misma tarea. Eso es una comparación hecha por un usuario, no una determinación de causa por parte de Anthropic, y conviene mantener la distinción.
Otro reporte describe condiciones claramente distintas. El issue #69336 (occurs immediately in new context window, abierto el 18 de junio de 2026 y abierto, Claude Code 2.1.173, Debian 13, un Claude Agent SDK autoalojado) informa de que la frecuencia sube después de que se ejecute el resumen de contexto (compact). Lleva area:agent-sdk, area:api y platform:linux, y describe abrir una conversación totalmente nueva como solución temporal. El issue #69517 (en Claude Cowork, 19 de junio de 2026, macOS, 2.1.183) se cerró como duplicado.
4. Lo que mostraron las capturas de paquetes: un cierre del servidor
La investigación de primera mano más profunda sobre esta clase de error es el issue #67766 (abierto el 12 de junio de 2026, todavía abierto). Quien lo reporta capturó paquetes en su propio entorno y correlacionó diez incidentes.
Fuente: las capturas de paquetes y transcripciones publicadas por quien reportó el issue #67766 de GitHub. Son mediciones de un solo usuario, no resultados verificados por Anthropic.
El detalle técnicamente revelador es que los cierres eran selectivos. Según el reporte, otras conexiones al mismo destino siguieron vivas durante el evento, y la que se cerró fue la conexión que pertenecía al proceso que hacía la petición. Las conexiones de otros dos procesos claude que corrían a la vez quedaron intactas. Una caída del enlace se los habría llevado a todos por delante; no fue así.
También observó que en cuatro de los diez incidentes llegaron tandas de cierres a varias conexiones del pool a la vez, y que tres se dispararon en el segundo :54 de minutos cercanos (01:19:54, 01:20:54 y 01:22:54 UTC), lo que interpreta como indicio de algo que corre en un ciclo de 60 segundos.
🟡 ¿Cuánta confianza merece esta sección?
El mensaje que aparece en el issue #67766 es «API Error: The socket connection was closed unexpectedly», con una redacción distinta a la de este artículo. No se puede afirmar que sean el mismo fallo. Dicho esto, hoy es la única evidencia pública a nivel de paquetes sobre el mismo tipo de comportamiento —una conexión que se cierra con un stream en vuelo—, así que sirve como hipótesis de trabajo. Conviene añadir que Anthropic no ha publicado ninguna explicación sobre ese reporte hasta la fecha.
5. Comprueba tu versión: la cronología de las correcciones
Esta es la parte más útil en la práctica. Si sigues el changelog oficial de Claude Code, verás que la gestión de los cortes de conexión a mitad de stream se ha mejorado varias veces. Cada entrada de abajo figura realmente en el changelog.
Ahora se conservan las respuestas parciales cuando la conexión se corta a mitad de stream. Antes salía un error en crudo y el indicador podía quedarse atascado en «running tool».
El aviso de estancamiento pasó a «Waiting for API response · will retry in …» y ahora salta tras 20 segundos de silencio en lugar de 10, así que los bailes breves ya no generan advertencia.
Corregido que los cortes breves de red a mitad de respuesta abortaran el turno. Los errores transitorios como ECONNRESET ahora se reintentan con backoff en vez de fallar.
Corregido que se descartaran las respuestas en streaming cuando llega un error de sobrecarga o de servidor a mitad de stream. Ahora la parte parcial se conserva con un aviso de respuesta incompleta, de ahí la variante Server error mid-response.
El pool de conexiones keep-alive ahora se desactiva tras un error de conexión obsoleta, de modo que los reintentos abren un socket nuevo. Habla directamente del patrón que describió el #67766: una conexión reutilizada que se cierra.
Ahora contrasta esa cronología con las versiones de los reportes anteriores.
| Reporte | Versión entonces | Correcciones aún no aplicadas |
|---|---|---|
| #69336 | 2.1.173 | Todas: 2.1.179 / 198 / 199 / 214 |
| #69415 | 2.1.181 | 2.1.198 / 199 / 214 (la mejora de reintentos y el arreglo del pool) |
| #69517 | 2.1.183 | 2.1.198 / 199 / 214 |
Los tres son anteriores a la 2.1.198, la versión que absorbe los cortes transitorios con reintentos. Así que lo primero que hay que mirar es tu propia versión.
claude --versionSi es inferior a 2.1.198, actualizar rinde más que diagnosticar. La última entrada del changelog al escribir esto es la 2.1.220, que incluye todas las correcciones anteriores.
Dicho esto, actualizar no garantiza que desaparezca. El changelog no contiene ninguna entrada que nombre «Connection closed» como tal; todo lo anterior son mejoras en la gestión de conexiones adyacente. Tómalo como la primera medida más rentable, no como una cura demostrada.
6. Condiciones que aumentan la probabilidad
Estos factores se repiten en los reportes.
Leer varios archivos grandes y producir un informe estructurado: cualquier cosa que mantenga el stream abierto mucho rato (#69415).
Se reporta que sube la frecuencia después de que se ejecute el resumen de contexto (#69336). Tras un resumen las peticiones suelen ser más grandes.
En las mediciones del #67766, las conexiones cerradas transportaban cuerpos de petición de 1 a 2,5 MB. Como referencia, el límite oficial de la Messages API es de 32 MB.
Proxies corporativos, VPN, enlaces de larga distancia. Es la capa que describe la documentación oficial al hablar de redes que cortan conexiones inactivas.
El changelog 2.1.186 corrigió peticiones de streaming que fallaban tras despertar la máquina. No dejes que el equipo se duerma en trabajos largos.
En el #67766, 87 de 171 incidentes ocurrieron menos de cinco segundos después de la llamada anterior, un patrón que los cortes por inactividad no explican solos.
7. Solucionarlo ya: lista de comprobación
Baja por la lista; lo más barato va primero.
| # | Qué hacer | Para qué |
|---|---|---|
| 1 | Responder continue | El paso de recuperación documentado. Reaprovecha lo que ya llegó en vez de empezar de cero. |
| 2 | Ejecutar claude --version y actualizar si es antigua | Te da la mejora de reintentos de la 2.1.198 y el arreglo del pool de la 2.1.214. Hazlo primero. |
| 3 | Revisar efectos secundarios (git status y similares) | Ver si alguna herramienta se ejecutó parcialmente antes del corte. Evita ejecuciones duplicadas. |
| 4 | Dividir la tarea | Respuestas más cortas equivalen a menos tiempo expuesto. Separa «lee todos los archivos y escribe el informe» en fases. |
| 5 | Saltarte el proxy o la VPN un rato y volver a probar | Aísla la capa 2. Si deja de pasar, la ruta es la culpable. |
| 6 | Desactivar suspensión y ahorro de energía; usar cable | Aísla la capa 1, sobre todo en un portátil con trabajos largos. |
| 7 | Probar en una sesión totalmente nueva | La solución temporal reportada en el #69336. A veces funciona cuando se dispara justo tras un resumen. |
| 8 | Si se reproduce, reportarlo con datos | Como recomienda la documentación oficial de la API, incluye el request_id (el identificador que empieza por req_) para acelerar la investigación. |
Lo que no hay que hacer. Desactivar la verificación TLS (NODE_TLS_REJECT_UNAUTHORIZED=0 y similares) porque «la conexión se cae» ataca un síntoma completamente distinto y tira por la borda la seguridad de tu tráfico. Los errores de certificado son otro error, con otra solución.
8. Para desarrolladores: cómo evitarlo desde la API/SDK
Si te topas con la misma clase de corte a través del Claude Agent SDK o de tu propia integración con la API, la documentación oficial de errores de la API de Claude ofrece pautas concretas de diseño.
La documentación recomienda la Messages API en streaming o la Message Batches API para peticiones largas, sobre todo por encima de 10 minutos. Un max_tokens alto sin streaming es la forma con más probabilidad de cortarse.
La documentación indica que configurar keep-alive de TCP reduce el impacto de los cortes por inactividad si escribes una integración directa. Los SDK oficiales ya lo hacen. Revísalo si montaste tu propio cliente HTTP.
Los SDK oficiales reintentan los fallos transitorios —errores de conexión, límites de tasa, 5xx— dos veces por defecto con backoff exponencial, respetando la cabecera retry-after. Una opción del cliente permite cambiarlo o desactivarlo.
La trampa que la documentación señala explícitamente: con SSE puede producirse un error después de que la API haya devuelto 200, así que no sigue el camino estándar de errores HTTP. Gestiona aparte los eventos de error a mitad de stream.
El propio Claude Code fue en esa dirección en la 2.1.179 y la 2.1.199. Guardar los bloques recibidos y pedir el resto cuesta menos —en tokens y en efectos secundarios— que descartarlo todo y reenviar.
En la 2.1.214, Claude Code cambió el pool keep-alive para desactivarlo tras un error de conexión obsoleta y que los reintentos abran un socket nuevo. Merece la pena comprobar si tu reintento está agarrando la misma conexión muerta.
Para cargas de trabajo en las que prefieres no dar por supuesta una conexión ininterrumpida —el procesamiento por lotes es el caso obvio—, la vía recomendada oficialmente es la Message Batches API, consultando los resultados por sondeo. Eso elimina el riesgo de red de raíz en vez de mitigarlo.
9. Cómo distinguirlo de errores parecidos
Los errores de transporte de Claude Code se parecen mucho. La forma más rápida de separarlos es por hasta dónde llegó la petición.
| Mensaje | Dónde se detuvo | Respuesta principal |
|---|---|---|
| Connection closed mid-response (este artículo) | Conectado y transmitiendo, y entonces se cortó | continue / actualizar / aislar la ruta |
| Response stalled mid-stream | Conexión viva pero en silencio | Tratado aparte (ojo al encadenado con el bucle de repetición) |
| Server error mid-response | Un error 5xx o de sobrecarga a mitad de stream | Esperar y reintentar. Ver el artículo sobre 529/500 |
| Unable to connect / SSL certificate verification failed | Nunca llegó a conectar | Proxy, CA corporativa, cortafuegos. Ver el artículo sobre errores de conexión |
| Prompt is too long | Rechazado antes de enviarse (la red está bien) | Recortar el contexto. Ver el artículo dedicado |
La bifurcación más importante es simplemente si apareció algo de respuesta en pantalla. Si no llegó ni un carácter, sospecha de la conexión misma: configuración y ruta. Si salió salida y luego se detuvo, eso prueba que la conexión funcionaba, así que deja de tocar ajustes y sigue los pasos de aislamiento de este artículo.
10. Estado oficial y lo que sigue sin confirmarse
Para evitar confusiones, esto es lo que puede confirmarse oficialmente y lo que no.
- El mensaje está documentado formalmente en la referencia de errores oficial y significa «la conexión se cayó»
- La salida ya transmitida se conserva, por diseño
- El paso de recuperación es responder
continue - Los fallos anteriores a cualquier salida visible se reintentan automáticamente
- Hubo correcciones de gestión de conexión en 2.1.179 / 198 / 199 / 214
- Servidores que envían un FIN a mitad de stream (medido en el #67766, pero bajo otro mensaje)
- La implicación de un barrido de 60 segundos (inferencia de quien reporta)
- Picos justo después de un compact (#69336)
- Que otros asistentes de IA no fallen en las mismas condiciones (comparación de quien reporta el #69415)
- Una explicación oficial de la causa por parte de Anthropic (sin respuesta pública en #69415, #69336 ni #67766)
- Una entrada de corrección que nombre «Connection closed» (esa cadena no aparece en el changelog)
- #69415, #69336 y #67766 siguen todos abiertos
En resumen: el síntoma y la respuesta están documentados oficialmente, pero no se ha publicado ninguna explicación oficial de por qué se corta. Con ese panorama, los hábitos operativos ganan a la caza de la causa raíz: mantén los turnos cortos, verifica el estado a medida que avanzas en operaciones con efectos secundarios y quédate en una versión actual.
Preguntas frecuentes
Q1. Cuando aparece «Connection closed mid-response», ¿se pierde lo que había hasta ese momento?
No. Como deja explícito la referencia de errores oficial, todo lo que ya se transmitió se conserva. Claude Code añade el aviso deliberadamente en lugar de reenviar, porque reenviar podría ejecutar dos veces las mismas llamadas a herramientas. Lo que falta suele ser solo las últimas frases o la última llamada a una herramienta.
Q2. ¿Qué debo responder para seguir desde donde se detuvo?
Responde continue. Es el paso de recuperación que nombra la referencia de errores oficial. Repetir la instrucción original arriesga duplicar operaciones que ya se ejecutaron.
Q3. ¿Se desperdician los tokens?
Lo generado hasta el corte se ha consumido. Quien reportó el issue #69336 señala que los tokens consumidos no se reembolsan. Justo por eso usar continue —en lugar de empezar de cero— importa tanto en coste como en tiempo.
Q4. ¿Es lo mismo que «Response stalled mid-stream»?
No. Según las definiciones oficiales, Connection closed significa «la conexión se cayó» y Response stalled significa «el stream dejó de enviar datos»: cortado frente a en silencio. En pantalla se parecen, pero la variante stalled se ha reportado junto a un bucle de repetición del modelo y la solución es distinta. Consulta el artículo sobre Response stalled mid-stream.
Q5. ¿Es culpa de mi red?
Puede serlo, pero no necesariamente. Quien reportó el issue #69415 lo vio en una conexión directa sin proxy ni cortafuegos, y las capturas de paquetes del issue #67766 indican que el cierre se inició desde el servidor. Salta primero cualquier proxy o VPN y comprueba si se sigue reproduciendo; si nada cambia, no es puramente local.
Q6. ¿Actualizar Claude Code lo soluciona?
Es lo primero que más rinde probar. El changelog oficial muestra que la 2.1.198 corrigió «los cortes breves de red a mitad de respuesta que abortaban el turno», y que la 2.1.214 cambió el pool keep-alive para desactivarlo tras un error de conexión obsoleta y que los reintentos abran un socket nuevo. El grueso de los reportes (2.1.173 a 2.1.183) es anterior a esas versiones. Pero como ninguna entrada del changelog nombra «Connection closed» como tal, actualizar es una mejora probable, no una cura garantizada.
Q7. Me pasa constantemente en tareas largas. ¿Hay alguna solución?
Dividir la tarea para que cada respuesta sea más corta es la opción más fiable. Los trabajos en bloque del tipo «lee todos los archivos grandes y escribe el informe» exponen el stream mucho tiempo; separar la lectura de la redacción acorta esa ventana y baja la probabilidad de toparse con un corte. El issue #69336 también reporta que abrir una conversación nueva ayudó temporalmente.
Q8. Como desarrollador, ¿cómo lo evito en mi propia aplicación?
Las pautas de la documentación oficial de la API de Claude son claras: (1) usa streaming siempre en respuestas largas y valora la Batches API más allá de 10 minutos; (2) configura keep-alive de TCP (los SDK oficiales ya lo hacen); (3) con SSE los errores pueden llegar tras un 200, así que gestiona aparte los eventos de error a mitad de stream; (4) ante un corte, guarda lo recibido y pide el resto. Incluye el request_id cuando contactes con soporte.
Q9. Me sale el mismo error en Claude Cowork y en el Agent SDK.
El mismo mensaje se ha reportado ahí. El issue #69517 lo reporta en Claude Cowork (cerrado como duplicado) y el #69336 a través de un Claude Agent SDK autoalojado. Es un comportamiento de la capa que gestiona las respuestas en streaming, así que el enfoque es el mismo: retomar en vez de reiniciar, mantenerse en una versión actual y diseñar bien los reintentos.
Artículos relacionados
- Claude Code: «court» en bucle infinito y «Response stalled mid-stream» — causas y solución
- Errores de red/proxy en Claude Code: Unable to connect to API y certificados TLS
- Claude Code: error 529 Overloaded y 500, qué significan y cómo resolverlos
- Error «Prompt is too long» en Claude Code: causas y soluciones
- Errores comunes de Claude Code y cómo solucionarlos — La referencia completa
