Contenido del artículo

Los errores de proxy asustan por lo repentinos que son. Hace un momento la solicitud funcionaba y ahora ves un misterioso 407, 502 o el mensaje tunnel connection failed. La buena noticia: detrás de cada uno de estos errores hay una causa clara y lógica. Esta guía te enseñará a leer estos mensajes como un libro abierto.

Introducción: por qué necesitas esta guía y qué obtendrás

Trabajar con proxies es como una conversación telefónica a través de un intérprete. Tu cliente habla con el proxy, el proxy habla con el sitio de destino y la respuesta regresa por la misma cadena. Cuando algo se rompe, es importante entender en qué punto exacto surgió el problema. De eso trata precisamente esta guía.

Qué obtendrás al final:

  • La capacidad de distinguir al instante un error de proxy de un error del sitio de destino.
  • Entender qué significan los códigos 407, 502, 504, 403 y el mensaje tunnel connection failed.
  • La habilidad de leer la salida del comando curl -v línea por línea, con una clara separación de los tramos cliente-proxy-servidor.
  • Ejemplos listos de diagnóstico con curl, Python requests y Node.js con textos de error reales.
  • Una tabla de diagnóstico rápido síntoma-causa-verificación que puedes imprimir y tener a mano.

Para quién es esta guía. Está escrita para quienes recién empiezan a trabajar con proxies, pero también contiene detalles avanzados para desarrolladores experimentados y especialistas en automatización. Si configuras scrapers, trabajas con multicuentas o simplemente quieres entender por qué tu script dejó de recibir datos de repente, este material es para ti.

Qué necesitas saber de antemano. Basta con una comprensión básica de qué es una URL, un puerto y una solicitud HTTP. No se requieren conocimientos profundos de redes. Explicaremos todos los términos en palabras sencillas a medida que avancemos.

Cuánto tiempo tomará. La primera lectura tomará alrededor de 30-40 minutos. Practicar los ejemplos en tu propio proyecto tomará otros 20-30 minutos. Después de eso, diagnosticar un error típico te tomará uno o dos minutos.

Aclaración importante sobre el tema. En esta guía analizamos únicamente los errores de la propia capa de proxy. El código 429 (demasiadas solicitudes) y las estrategias de reintentos no se tratan aquí, porque es un tema grande y aparte con su propia lógica y enfoques. Para el 429 se necesita un material aparte sobre reintentos y límites. Aquí nos concentramos estrictamente en el diagnóstico de fallos de conexión del proxy.

Preparación previa: herramientas y accesos

Antes de empezar el diagnóstico, reunamos un conjunto de herramientas. Todas son gratuitas y funcionan en cualquier sistema operativo.

Herramientas necesarias

  1. Instala curl. En la mayoría de los sistemas Linux y macOS ya viene incluido. Verifícalo con el comando curl --version. Si ves un número de versión, todo está listo.
  2. En Windows, curl forma parte del sistema a partir de las versiones modernas. Abre PowerShell e ingresa el mismo comando de verificación.
  3. Instala Python versión 3.10 o superior si planeas usar los ejemplos con requests. Verifícalo con el comando python --version.
  4. Instala la biblioteca requests con el comando pip install requests en la terminal.
  5. Instala Node.js versión 20 o superior para los ejemplos en JavaScript. Verifícalo con el comando node --version.

Qué necesitas preparar

  • Los datos de tu proxy: dirección del host, puerto, usuario y contraseña, si son necesarios.
  • Una dirección de destino de prueba a la que te dirigirás. Para las verificaciones es cómodo usar un sitio simple que devuelva información sobre la solicitud.
  • Un editor de texto para guardar los registros y las notas del diagnóstico.

Consejo: Crea un archivo de texto aparte llamado diagnostic-notes. Anota allí cada comando y su resultado. Esto te salvará cuando, media hora después, olvides qué ya verificaste.

⚠️ Atención: Nunca guardes el usuario y la contraseña del proxy en chats grupales, repositorios públicos ni capturas de pantalla. Una filtración de estos datos da a terceros acceso a tu tráfico. Guárdalos en un gestor de contraseñas seguro.

✅ Verificación: En este punto debes poder ejecutar con éxito los tres comandos de verificación de versiones: curl, python y node. Si al menos uno no funciona, vuelve a instalar la herramienta correspondiente.

Conceptos básicos en palabras sencillas

Para que el diagnóstico sea consciente, repasemos algunos términos clave. No te saltes esta sección, aunque los términos te parezcan conocidos.

Qué es un proxy en realidad

Un proxy es un intermediario entre tu programa y el sitio de destino. Tu solicitud llega primero al proxy, y el proxy la transmite más adelante. La respuesta regresa por el mismo camino. Debido a esta intermediación, cualquier error puede surgir en tres lugares: en tu cliente, en el propio proxy o en el sitio de destino.

La división principal: cliente, proxy, servidor

Memoriza los tres eslabones de la cadena. El primer eslabón es tu cliente, es decir, el programa que envía la solicitud. El segundo eslabón es el proxy, el intermediario. El tercer eslabón es el servidor de destino, el sitio al que quieres llegar. Todo el diagnóstico se reduce a la pregunta: ¿en cuál de los tres eslabones ocurrió el fallo?

Los códigos HTTP en pocas palabras

Los sitios y los proxies responden con códigos numéricos. Los códigos que empiezan con 4 (por ejemplo, 407, 403) generalmente indican un problema del lado de la solicitud o del acceso. Los códigos que empiezan con 5 (502, 504) indican un problema del lado del servidor o del intermediario. Pero aquí hay una sutileza traicionera: el código 502 puede enviarlo tanto el sitio de destino como el propio proxy. Aprender a distinguirlos es uno de los objetivos principales de la guía.

Diferencia entre HTTP y HTTPS a través de un proxy

Cuando vas a un sitio normal por HTTP, el proxy ve toda la solicitud completa. Cuando vas a un sitio protegido por HTTPS, el proxy no puede leer el contenido. En su lugar, el cliente le pide al proxy que cree un túnel protegido con un comando especial llamado CONNECT. Por eso el error tunnel connection failed aparece únicamente en HTTPS. Lo analizaremos en detalle por separado.

Consejo: Ten en mente una imagen simple. El cliente toca la puerta del proxy. El proxy decide si lo deja pasar. Luego el proxy toca la puerta del sitio. El sitio decide si responder. El error surge en el toque que falló.

Paso 1: Cómo distinguir un error de proxy de un error del sitio de destino

Objetivo de esta etapa: aprender a entender en pocos segundos quién tiene la culpa: el proxy o el sitio. Esta es una habilidad fundamental con la que comienza cualquier diagnóstico.

Principio principal de separación

La pregunta clave es esta: ¿tu solicitud llegó al sitio de destino o se quedó atascada en el proxy? Si la solicitud se quedó atascada en el proxy, la culpa es de la capa de proxy. Si la solicitud llegó al sitio y el sitio respondió, entonces el problema está del lado del sitio.

  1. Mira el código de error y el texto del mensaje.
  2. Determina quién envió esa respuesta: el proxy o el servidor. El encabezado de la respuesta y el contenido te lo dirán.
  3. Si en el texto del error se menciona directamente la palabra proxy, tunnel o el nombre del programa proxy, casi con seguridad la culpa es de la capa de proxy.
  4. Si la respuesta contiene una página HTML habitual del sitio de destino con su logotipo y diseño, significa que la solicitud llegó al sitio.

Tres señales rápidas de un error de proxy

  • Código 407. Este código existe únicamente en los proxies. El sitio de destino nunca lo envía. Si ves 407, estás definitivamente en la capa de proxy.
  • El texto tunnel connection failed o Received HTTP code del proxy. Estas formulaciones las genera precisamente el intermediario.
  • Rechazo instantáneo de la conexión. Si la solicitud falla casi de inmediato, antes incluso de que pudiera llegar al sitio, lo más probable es que el problema esté entre el cliente y el proxy.

Consejo: Haz un experimento de control. Realiza esa misma solicitud directamente, sin proxy. Si directamente todo funciona y a través del proxy no, entonces el problema está en la capa de proxy o en su interacción con el sitio. Esto descarta la mitad de las hipótesis en un minuto.

Ejemplo con curl para una verificación rápida

Ejecuta la solicitud a través del proxy con la bandera de salida detallada. El comando es así: curl -v -x http://usuario:contraseña@host:puerto https://sitio-de-ejemplo. La bandera -v muestra todo el diálogo. La bandera -x especifica el proxy. Fíjate en las líneas que empiezan con flechas y asteriscos. Hablaremos de ellas en detalle en un paso aparte sobre la lectura de registros.

⚠️ Atención: Nunca saques conclusiones de una sola solicitud a un sitio inestable. Repite la solicitud dos o tres veces. Un fallo puntual de red puede parecer un error de proxy, aunque el proxy no tenga nada que ver.

✅ Verificación: Debes poder responder, para cualquier mensaje de error, a la pregunta: ¿esto lo envió el proxy o el sitio? Si puedes hacerlo, avanza. Si todavía dudas, vuelve a las tres señales rápidas de arriba.

Paso 2: Error 407 Proxy Authentication Required

Objetivo de esta etapa: aprender a corregir el error de autenticación más frecuente en el proxy y entender en qué se diferencia del código similar 401.

Qué significa 407 y en qué se diferencia de 401

El código 407 dice literalmente lo siguiente: el proxy exige que te identifiques con usuario y contraseña, pero no lo hiciste o lo hiciste mal. La diferencia clave con el 401: el código 401 lo envía el sitio de destino cuando es él quien exige la autorización. Y el código 407 lo envía precisamente el proxy. Si ves 407, significa que ni siquiera llegaste al sitio: te detuvo el intermediario en la entrada.

Dónde exactamente se pierden el usuario y la contraseña

Con mayor frecuencia, los datos se pierden en tres lugares.

  1. El usuario y la contraseña no se transmitieron en absoluto en el comando. El cliente tocó la puerta del proxy de forma anónima y el proxy lo rechazó.
  2. Los datos se transmitieron, pero con un error tipográfico. Un espacio de más o una distribución de teclado incorrecta, y la autorización no pasa.
  3. Los datos se transmitieron correctamente, pero la contraseña contiene caracteres especiales que rompen la estructura de la cadena de conexión. Esta es la causa más traicionera.

Caracteres especiales en la contraseña y codificación URL

La cadena de conexión al proxy se ve así: usuario, dos puntos, contraseña, arroba, host, dos puntos, puerto. El problema es que los dos puntos, la arroba, la barra y otros caracteres tienen un significado especial dentro de esta cadena. Si tu contraseña contiene, por ejemplo, una arroba o dos puntos, el programa la entenderá mal y romperá la cadena en el lugar equivocado.

La solución se llama codificación URL. Los caracteres especiales se reemplazan por un código formado por el signo de porcentaje y dos cifras o letras. Por ejemplo, la arroba se convierte en porcentaje cuarenta, los dos puntos se convierten en porcentaje tres A, la barra se convierte en porcentaje dos F, el espacio se convierte en porcentaje veinte.

  1. Encuentra en tu contraseña todos los caracteres especiales.
  2. Reemplaza cada uno por su código URL.
  3. Vuelve a armar la cadena de conexión con la contraseña codificada.
  4. Repite la solicitud.

Consejo: No codifiques la contraseña a mano si es compleja. En Python hay una función de codificación del módulo urllib.parse llamada quote. Pásale la contraseña y te devolverá una versión segura. Esto elimina los errores de escritura manual.

Ejemplo con curl

El texto real del error con autorización incorrecta se ve así: curl (56) Received HTTP code 407 from proxy after CONNECT. O, en un sitio HTTP: HTTP 407 Proxy Authentication Required. El comando correcto con autorización: curl -v --proxy-user usuario:contraseña -x http://host:puerto https://sitio-de-ejemplo. Usar la bandera --proxy-user suele ser más confiable que escribir los datos directamente en la dirección, porque curl mismo procesará los caracteres correctamente.

Ejemplo con Python requests

En requests, el proxy se especifica mediante un diccionario. Las claves http y https, los valores son las cadenas de conexión. Si la contraseña contiene caracteres especiales, envuélvela en la función quote. Un error típico en la respuesta del objeto: response.status_code devolverá 407, y en el texto habrá una mención a Proxy Authentication Required. Verifica precisamente el código de estado, no solo el texto.

Ejemplo con Node.js

En Node, al usar clientes de proxy populares, el proxy se especifica mediante un agente especial. El error real se ve como un objeto con el campo statusCode igual a 407 o como una promesa rechazada con un mensaje de error de autorización del túnel. Asegúrate de enviar el encabezado de autorización del proxy, y no el encabezado de autorización del sitio: son cosas distintas.

⚠️ Atención: El encabezado de autorización para el proxy y el encabezado de autorización para el sitio son dos encabezados diferentes. Uno se llama Proxy-Authorization y el otro Authorization. Si los confundes, obtendrás un 407 del proxy o un 401 del sitio. Verifica cuál encabezado envía tu biblioteca.

✅ Verificación: Después de corregir la autorización, el código de respuesta debe cambiar de 407 a cualquier otro. Aunque el sitio responda con su propio error, ya es un avance: pasaste el proxy y llegaste al sitio.

Paso 3: Error 502 del proxy

Objetivo de esta etapa: aprender a entender cuándo el 502 significa un problema del sitio de destino y cuándo un fallo del propio canal del proxy.

Qué significa 502

El código 502 se llama Bad Gateway, es decir, puerta de enlace incorrecta. Dice que el intermediario intentó dirigirse al siguiente eslabón, pero recibió una respuesta confusa o interrumpida. El problema es que el 502 puede llegar en dos situaciones completamente distintas, y exteriormente se parecen.

Cuándo la culpa es del host de destino

Primera situación: el proxy se comunicó con éxito con el sitio de destino, pero el sitio devolvió basura, cortó la conexión o él mismo no pudo obtener respuesta de su backend. En este caso, el proxy transmitió honestamente el 502 como constatación: llegué al sitio, pero el sitio respondió mal.

  1. Haz esa misma solicitud directamente, sin proxy.
  2. Si directamente el sitio también responde 502 o se cuelga, entonces la culpa es del sitio, no del proxy.
  3. En este caso, cambiar el proxy es inútil. El problema está del lado del destino.

Cuándo la culpa es del propio canal

Segunda situación: el propio proxy es inestable, su canal superior se cortó, o el proxy ni siquiera pudo establecer correctamente la conexión con el sitio. Entonces el 502 es una señal de un intermediario enfermo.

  1. Haz una solicitud a través de ese mismo proxy a un sitio que sea claramente estable.
  2. Si incluso un sitio estable devuelve 502, entonces el problema está en el canal del proxy.
  3. Prueba otro proxy u otro nodo, si tienes alguno disponible.

Consejo: El método de verificación cruzada funciona sin fallar. Cambia una sola variable a la vez. Primero fija el proxy y cambia el sitio. Luego fija el sitio y cambia el proxy. La intersección de los resultados mostrará al culpable.

Textos de error reales

En curl verás una respuesta HTTP con el código 502 y, a menudo, una página HTML con la inscripción Bad Gateway. A veces, en los encabezados de la respuesta se ve la señal de qué servidor envió la respuesta. En Python requests es response.status_code igual a 502. En Node es el campo statusCode igual a 502. Presta atención al cuerpo de la respuesta: una página bien diseñada del sitio de destino indica que la solicitud llegó al sitio, y una página técnica y escueta suele provenir del proxy.

⚠️ Atención: No te apresures a culpar al proxy ante el primer 502. Los sitios de destino devuelven 502 muy a menudo, sobre todo bajo carga. Haz siempre una solicitud de control directamente, antes de cambiar la configuración del proxy.

✅ Verificación: Debes poder decir con seguridad, según los resultados de dos solicitudes cruzadas: este 502 es del sitio o del proxy. Si todavía no puedes, repite ambas solicitudes de control y compara los resultados.

Paso 4: Error 504 y tiempos de espera

Objetivo de esta etapa: aprender a distinguir dos tipos de timeout radicalmente distintos y a configurarlos correctamente en el cliente.

Qué significa 504

El código 504 se llama Gateway Timeout, es decir, la puerta de enlace no esperó la respuesta. Dice que el intermediario esperó demasiado tiempo una respuesta del siguiente eslabón y se rindió. Pero para entender dónde exactamente se atascó el tiempo, hay que dividir dos tipos de timeout.

Connect timeout frente a read timeout

Hay dos momentos de espera completamente diferentes.

  • Connect timeout: es el tiempo para establecer la conexión misma. El cliente intenta comunicarse con el proxy o el proxy con el sitio. Si la conexión no se establece en el tiempo previsto, se activa el connect timeout. Por lo general, es señal de que la dirección no está disponible o el puerto está cerrado.
  • Read timeout: es el tiempo de espera de la respuesta después de que la conexión ya está establecida. La conexión existe, la solicitud se envió, pero los datos no llegan. Por lo general, es señal de que el sitio tarda en pensar o se colgó en el procesamiento.

Cómo separarlos en el cliente

El diagnóstico correcto comienza con la configuración separada de estos dos timeouts. Entonces entenderás de inmediato en qué etapa se atascó el tiempo.

  1. En curl usa la bandera --connect-timeout para limitar el tiempo de establecimiento de la conexión. Por separado, la bandera --max-time limita el tiempo total de toda la operación.
  2. En Python requests, el parámetro timeout se puede pasar como una tupla de dos números. El primer número es el connect timeout, el segundo es el read timeout. Por ejemplo, timeout de cinco y treinta segundos.
  3. En Node, en la mayoría de los clientes hay configuraciones separadas para el tiempo de conexión y para el tiempo de espera de la respuesta. Ajusta valores diferentes para ver cuál se activó.

Cómo leer el resultado

Si se activó el connect timeout, significa que ni siquiera estableciste la conexión. Verifica la disponibilidad del proxy y la corrección del puerto. Si se activó el read timeout, significa que la conexión existía, pero la respuesta no llegó a tiempo. Verifica si el sitio está sobrecargado y si tu solicitud no es demasiado pesada.

Consejo: Configura el connect timeout pequeño, alrededor de cinco segundos. El establecimiento de la conexión ocurre rápido o no ocurre. Y el read timeout configúralo con margen, porque algunas páginas realmente tardan más en preparar la respuesta.

⚠️ Atención: Un read timeout demasiado pequeño provoca errores falsos. Cortarás respuestas normales, pero lentas, y pensarás que el proxy está roto. Verifica siempre si no fuiste tú quien puso un límite demasiado estricto.

Textos de error reales

En curl, el connect timeout se ve como el mensaje Connection timed out después de stderr. En Python requests es la excepción ConnectTimeout para la conexión y ReadTimeout para la respuesta. El nombre mismo de la excepción te dice de inmediato qué etapa falló. En Node verás un error con el código ETIMEDOUT o un mensaje aparte sobre exceso de tiempo de respuesta.

✅ Verificación: Después de configurar timeouts separados, debes recibir en el error una indicación clara: es un timeout de conexión o un timeout de lectura. Si solo ves la palabra general timeout sin aclaración, significa que los timeouts aún no están separados.

Paso 5: Error tunnel connection failed y el método CONNECT

Objetivo de esta etapa: entender por qué este error aparece solo en sitios protegidos y cómo diagnosticarlo.

Por qué el error llega solo en HTTPS

Cuando vas a un sitio HTTP normal, el proxy simplemente reenvía tu solicitud. Pero cuando vas a un sitio HTTPS, el contenido está cifrado y el proxy no puede leerlo. Por eso el cliente primero envía al proxy un comando especial CONNECT con la dirección del sitio. Este comando significa una petición: por favor, constrúyeme un túnel protegido hasta esta dirección, me comunicaré con el sitio directamente a través de ti.

Si el proxy, por alguna razón, no pudo construir el túnel, devuelve el error tunnel connection failed. En HTTP normal no existe ese comando, por eso ese error no ocurre en HTTP. Esta es tu principal señal identificadora.

Causas principales del fallo del túnel

  • El proxy no pudo conectarse a la dirección de destino. Puede que el sitio no esté disponible o el puerto esté cerrado.
  • El proxy prohíbe el método CONNECT a esa dirección o puerto. Algunos proxies permiten solo ciertos puertos.
  • La autorización no pasó. En este caso, a menudo verás una combinación: primero el intento de CONNECT, luego el código 407.
  • El proxy está sobrecargado o su canal superior se cortó en el momento de construir el túnel.

Cómo diagnosticar

  1. Ejecuta curl -v a una dirección HTTPS y encuentra en la salida la línea con CONNECT. Muestra el momento de la solicitud del túnel.
  2. Mira qué respuesta llegó al CONNECT. Una respuesta con el código 200 significa que el túnel se construyó. Cualquier otro código significa un fallo.
  3. Si cerca ves un 407, entonces el problema está en la autorización, no en el túnel mismo. Vuelve al paso sobre el 407.
  4. Si ves un rechazo de conexión, entonces el proxy no pudo llegar al sitio.

Consejo: Verifica que te diriges precisamente a un puerto permitido. Los puertos clásicos para conexiones protegidas generalmente están permitidos, y muchos proxies bloquean los puertos no estándar. Cambiar el puerto a uno estándar suele resolver el problema al instante.

Textos de error reales

En curl es un mensaje del tipo curl (56) Received HTTP code del proxy after CONNECT o directamente tunnel connection failed. En Python requests es la excepción ProxyError con un mensaje anidado sobre el túnel fallido. En Node es un error con el texto de que la conexión de túnel no se pudo establecer, a menudo con la indicación del código de estado del proxy.

⚠️ Atención: No confundas el fallo del túnel con un error de certificado. Si el túnel se construyó, pero luego se queja del certificado protegido del sitio, eso ya es otro problema, no relacionado con la capa de proxy. Mira en qué etapa exactamente surgió el error: antes de la respuesta al CONNECT o después.

✅ Verificación: Debes encontrar en la salida de curl la línea con la respuesta al CONNECT y entender, por su código, si el túnel se construyó o no. Respuesta 200: hay túnel. Otro código: busca la causa del fallo.

Paso 6: Error 403 del proxy

Objetivo de esta etapa: aprender a reconocer cuándo el 403 lo envía el proxy por límites, geografía o puerto prohibido.

Qué significa 403 en el contexto del proxy

El código 403 se llama Forbidden, es decir, prohibido. Por lo general, este código lo envía el sitio de destino cuando cierra el acceso. Pero el proxy también puede enviar un 403 cuando él mismo decide no dejar pasar tu solicitud. La tarea es entender quién puso exactamente la prohibición.

Tres causas de un 403 del proxy

  • Límites. El proxy puede limitar la cantidad de solicitudes, el volumen de tráfico o el número de conexiones simultáneas. Al superarlos, devuelve 403 como negativa a atender.
  • Restricción geográfica. Algunos proxies permiten el acceso solo a determinadas regiones o, por el contrario, prohíben ciertas direcciones. Una solicitud a una dirección cerrada recibe 403.
  • Puerto prohibido. El proxy puede permitir solo puertos estándar. Dirigirse a un puerto no estándar termina en negativa.

Cómo distinguir un 403 del proxy de un 403 del sitio

  1. Mira el cuerpo de la respuesta. Una página bien diseñada del sitio de destino, con su diseño, significa que la prohibición la puso el sitio.
  2. Una página técnica y escueta o una mención al proxy en el texto significa que la prohibición la puso el intermediario.
  3. Haz esa misma solicitud directamente. Si directamente el sitio también devuelve 403, y a través del proxy también, entonces la culpa es del sitio.
  4. Si directamente el sitio abre y a través del proxy devuelve 403, busca la causa en los límites o restricciones del proxy.

Consejo: Revisa la documentación o el panel de control de tu proxy en busca de límites. A menudo, en el área personal se ve si el tráfico se agotó o si se alcanzó el límite de solicitudes. Esta es la forma más rápida de confirmar la causa.

⚠️ Atención: No intentes eludir los límites del proxy con trucos. Si llegaste al límite de tu plan, la solución correcta es ampliar el plan u optimizar la cantidad de solicitudes. Eludir las restricciones técnicas del servicio viola los términos de uso.

Textos de error reales

En curl es una respuesta HTTP 403 Forbidden con un cuerpo que indicará la fuente. En Python requests es response.status_code igual a 403. En Node es statusCode igual a 403. Analiza siempre el cuerpo de la respuesta junto con el código, porque precisamente el cuerpo revela al verdadero autor de la prohibición.

✅ Verificación: Debes poder determinar, por el cuerpo de la respuesta y el resultado de la solicitud directa, quién envió el 403. Si es el proxy, revisa los límites, la geografía y el puerto. Si es el sitio, la causa no está en la capa de proxy.

Paso 7: Corte de conexión sin respuesta: connection reset y EOF

Objetivo de esta etapa: aprender a diagnosticar los casos más misteriosos, cuando no hay respuesta alguna y la conexión simplemente se corta.

Qué son estos errores

A veces no recibes ningún código HTTP. En su lugar, la conexión se corta de repente. Hay dos manifestaciones típicas.

  • Connection reset. Literalmente: conexión restablecida. Una de las partes cerró bruscamente el canal sin completar el intercambio. Como si el interlocutor colgara el teléfono a mitad de la palabra.
  • EOF, unexpected end of file. Literalmente: fin de datos inesperado. El cliente esperaba la continuación de la respuesta, pero el flujo de datos terminó de repente.

Qué mirar en primer lugar

  1. Determina el momento del corte. ¿Ocurrió antes de la respuesta al CONNECT, durante el envío de la solicitud o durante la recepción de la respuesta? La salida de curl -v mostrará la última línea exitosa antes del corte.
  2. Si el corte ocurrió al principio, al conectarse al proxy, lo más probable es que el problema esté en el propio proxy o en la ruta de red hasta él.
  3. Si el corte ocurrió después de establecer el túnel, durante la comunicación con el sitio, es más probable que el problema esté del lado del sitio o de un canal inestable.
  4. Repite la solicitud varias veces. Un corte que se repite de manera estable indica una causa sistémica. Uno aleatorio indica una inestabilidad temporal de la red.

Causas frecuentes

  • El proxy está sobrecargado y cierra forzosamente las conexiones sobrantes.
  • El canal superior del proxy es inestable y se rompe.
  • El sitio de destino cierra la conexión por sus propias restricciones.
  • Problemas de red entre los eslabones de la cadena.

Consejo: En caso de cortes aleatorios, lleva estadísticas. Haz, por ejemplo, veinte solicitudes seguidas y cuenta cuántas se cortaron. Si se corta una de cada veinte, es una inestabilidad tolerable. Si se corta la mitad, entonces hay un problema sistémico que hay que resolver.

Textos de error reales

En curl es Connection reset by peer o Empty reply from server. En Python requests es la excepción ConnectionError con un mensaje anidado sobre el restablecimiento de la conexión. En Node es un error con el código ECONNRESET. Estos mensajes no contienen un código HTTP precisamente porque el intercambio HTTP no terminó normalmente.

⚠️ Atención: Un corte sin respuesta se confunde fácilmente con un timeout. La diferencia es que en el timeout el cliente mismo termina la espera, mientras que en el reset la otra parte cierra activamente el canal. Mira el texto del error: la palabra reset indica un restablecimiento activo, la palabra timeout indica el vencimiento de la espera.

✅ Verificación: Debes poder determinar, por la última línea de la salida de curl, en qué etapa se cortó la conexión. Esto reduce de inmediato el círculo de sospechosos a uno o dos eslabones.

Paso 8: Práctica: leamos curl -v línea por línea

Objetivo de esta etapa: aprender a ver en la salida de curl la frontera entre el cliente, el proxy y el servidor. Esta es la culminación de toda la guía.

Qué significan los símbolos al inicio de las líneas

La salida de curl -v usa símbolos especiales al inicio de cada línea, y esta es tu llave principal para entender.

  • El asterisco al inicio de la línea significa un mensaje informativo del propio curl. Son comentarios del cliente sobre lo que está haciendo: establece la conexión, construye el túnel, verifica el certificado.
  • La flecha hacia la derecha significa datos que el cliente envía al proxy o al servidor. Es la solicitud saliente.
  • La flecha hacia la izquierda significa datos que el cliente recibe en respuesta. Es la respuesta entrante.

Dónde pasa la frontera cliente-proxy-servidor

Analicemos el camino típico a un sitio protegido a través de un proxy. Primero curl informa con un asterisco que se conecta al proxy por la dirección y el puerto indicados. Este es el tramo cliente-proxy. Luego viene la flecha saliente con el comando CONNECT: el cliente pide al proxy que construya un túnel. Después, la flecha entrante con la respuesta al CONNECT: es la respuesta del proxy. Si el código es 200, el túnel está construido y la frontera se desplaza: a partir de ahí, todo el intercambio es ya cliente-servidor a través del túnel.

Análisis de un registro real

Imaginemos que ves esta secuencia. Una línea con asterisco: me conecto a la dirección del proxy y al puerto. Esto significa que el cliente encontró el proxy. La siguiente línea con asterisco: conexión con el proxy establecida. Excelente, el primer tramo superado. Luego la flecha saliente: CONNECT a la dirección del sitio de destino. El cliente pidió el túnel. Después, la flecha entrante: respuesta al CONNECT con el código. Aquí está la bifurcación clave.

  1. Si el código de respuesta al CONNECT es 200, el túnel está construido. Seguimos leyendo.
  2. Si el código es 407, el proxy exige autorización. El problema está en la capa de proxy, tramo cliente-proxy. Ve al paso sobre el 407.
  3. Si la línea dice tunnel connection failed, el proxy no pudo construir el túnel. La causa está entre el proxy y el sitio.

Supongamos que el túnel se construyó. Después vienen asteriscos sobre la verificación de la conexión protegida con el sitio. Este es ya el tramo cliente-servidor. Luego la flecha saliente con la solicitud real: la línea de solicitud y los encabezados. Presta atención: hasta este momento el sitio no vio tu solicitud en absoluto, estaba ocupado construyendo el túnel. Y finalmente la flecha entrante con el código de respuesta del sitio. Aquí comienza la zona de responsabilidad del sitio de destino.

Cómo aplicar esto para el diagnóstico

  1. Encuentra la línea de establecimiento de la conexión con el proxy. Si no está o tiene un error, el problema está entre el cliente y el proxy.
  2. Encuentra la respuesta al CONNECT. Por su código determina si la capa de proxy pasó.
  3. Encuentra la flecha entrante con la respuesta del sitio. Si existe, significa que llegaste al sitio, y cualquier error aquí ya es zona del sitio.
  4. La última línea antes del corte siempre sugiere en qué tramo se rompió todo.

Consejo: Lee la salida de arriba hacia abajo como la crónica del viaje de la solicitud. Cada línea es un paso del camino. En cuanto llegues a la línea con el error o el corte, mira la línea exitosa anterior. Ella indicará el último eslabón vivo.

⚠️ Atención: La bandera -v muestra los encabezados, incluida la línea de autorización del proxy. Si compartes el registro con alguien para pedir ayuda, tacha obligatoriamente la línea con los datos de autorización. De lo contrario, revelarás tu usuario y contraseña.

✅ Verificación: Toma cualquier registro tuyo de curl -v y márcalo: dónde está el tramo cliente-proxy, dónde la respuesta al CONNECT, dónde comienza la zona del sitio. Si trazas con seguridad estas fronteras, has dominado la habilidad principal del diagnóstico.

Paso 9: Tabla de diagnóstico rápido síntoma-causa-verificación

Objetivo de esta etapa: obtener un manual listo al que puedas recurrir en el momento de cualquier error.

Cómo usar la tabla

Encuentra tu síntoma en la primera columna. Lee la causa probable. Realiza la acción de la tercera columna en primer lugar: es la que con mayor probabilidad confirmará o refutará la causa.

Síntoma: código 407

Causa probable: no se transmitieron o son incorrectos los datos de autorización del proxy, o los caracteres especiales en la contraseña rompieron la cadena de conexión. Qué verificar primero: la corrección del usuario y la contraseña, así como la codificación URL de los caracteres especiales en la contraseña.

Síntoma: tunnel connection failed en HTTPS

Causa probable: el proxy no pudo construir el túnel hacia el sitio, posiblemente por un puerto prohibido o por la indisponibilidad del sitio. Qué verificar primero: la respuesta al CONNECT en la salida de curl -v y la permisibilidad del puerto de destino.

Síntoma: código 502

Causa probable: mala respuesta del siguiente eslabón; la culpa es del sitio o de un canal inestable del proxy. Qué verificar primero: la solicitud cruzada: el mismo sitio directamente y el mismo proxy a un sitio estable.

Síntoma: código 504

Causa probable: venció el tiempo de espera; hay que entender si fue el de la conexión o el de la respuesta. Qué verificar primero: connect timeout y read timeout separados, para ver qué etapa se demoró.

Síntoma: código 403 a través del proxy

Causa probable: límites del proxy, restricción geográfica o puerto prohibido. Qué verificar primero: el cuerpo de la respuesta en busca de la fuente de la prohibición y el panel de control del proxy en busca de límites agotados.

Síntoma: connection reset o ECONNRESET

Causa probable: una de las partes cerró forzosamente la conexión, a menudo un proxy sobrecargado o un canal inestable. Qué verificar primero: la etapa del corte por la última línea de curl -v y la repetibilidad del problema en una serie de solicitudes.

Síntoma: EOF, empty reply

Causa probable: el flujo de datos se cortó sin llegar al final de la respuesta. Qué verificar primero: en qué tramo ocurrió el corte, antes o después de la respuesta al CONNECT.

Síntoma: connect timeout

Causa probable: es imposible establecer la conexión, la dirección no está disponible o el puerto está cerrado. Qué verificar primero: la disponibilidad de la dirección del proxy y la corrección del puerto.

Síntoma: read timeout

Causa probable: la conexión existe, pero la respuesta no llega; el sitio tarda en procesar o se colgó. Qué verificar primero: si tu read timeout no es demasiado pequeño y si el sitio no está sobrecargado.

Consejo: Imprime esta tabla o guárdala en tus notas. En el momento del error real, bajo presión, es fácil olvidar la lógica. Un manual listo ahorra nervios y tiempo.

✅ Verificación: Pasa por la tabla cada uno de tus errores recientes. Para cualquiera de ellos debes conocer la primera acción de verificación.

Verificación del resultado: lista de control del diagnosticador

Asegúrate de haber dominado todas las habilidades clave. Recorre la lista de control.

  • Sabes responder en segundos quién envió el error: el proxy o el sitio.
  • Entiendes la diferencia entre 407 y 401 y sabes corregir la autorización, incluidos los caracteres especiales en la contraseña.
  • Distingues un 502 del sitio de un 502 del proxy mediante la verificación cruzada.
  • Separas connect timeout y read timeout y sabes qué significa cada uno.
  • Entiendes por qué tunnel connection failed ocurre solo en HTTPS y sabes leer la respuesta al CONNECT.
  • Reconoces las tres causas de un 403 del proxy: límites, geografía y puerto.
  • Diagnosticas los cortes de conexión por la etapa en que ocurrieron.
  • Lees la salida de curl -v línea por línea y trazas las fronteras cliente-proxy-servidor.

Cómo ponerte a prueba

  1. Toma tres registros reales con errores distintos.
  2. Para cada uno, determina el eslabón culpable en un minuto.
  3. Nombra la primera acción de verificación según la tabla.
  4. Si te salió con los tres, el diagnóstico está dominado.

✅ Verificación: El indicador de éxito es que ya no entras en pánico al ver un error de proxy, sino que lo descompones con calma por los eslabones de la cadena.

Errores típicos y soluciones

Problema: cambio el proxy de inmediato ante cualquier error

Causa: no tengo el hábito de la verificación cruzada. Solución: haz siempre una solicitud de control directamente y a un sitio estable, antes de cambiar la configuración. La mitad de los errores resulta estar del lado del sitio.

Problema: la contraseña con arroba rompe la conexión

Causa: el carácter especial no está codificado y rompe la cadena. Solución: aplica la codificación URL a la contraseña o usa un parámetro de autorización aparte en lugar de escribirla en la dirección.

Problema: confundo 407 y 401

Causa: no distingo la autorización del proxy de la autorización del sitio. Solución: recuerda que el 407 siempre es del proxy y el 401 siempre es del sitio. Verifica qué encabezado envías: Proxy-Authorization o Authorization.

Problema: un timeout demasiado estricto corta solicitudes normales

Causa: el read timeout está configurado demasiado pequeño. Solución: separa los timeouts de conexión y de lectura, dale margen al read para páginas lentas.

Problema: tunnel connection failed en un puerto no estándar

Causa: el proxy prohíbe el CONNECT a ese puerto. Solución: usa un puerto estándar para conexiones protegidas o averigua con el proxy la lista de puertos permitidos.

Problema: veo un 502 y pienso que el proxy está muerto

Causa: no verifiqué quién envió el 502. Solución: verificación cruzada. A menudo el 502 viene de un sitio de destino sobrecargado y el proxy está en buen estado.

Problema: revelé el usuario y la contraseña en un registro

Causa: compartí la salida de curl -v sin limpiarla. Solución: tacha siempre la línea de autorización antes de enviar el registro a alguien y, de ser posible, cambia los datos comprometidos.

Problema: considero un corte de conexión como un timeout

Causa: no distingo reset de timeout. Solución: mira el texto del error. Reset es el cierre activo por la otra parte, timeout es el vencimiento de tu espera. Son causas diferentes.

Funciones adicionales para avanzados

Registro permanente

Configura el guardado de registros detallados de todas las solicitudes de proxy en tu aplicación. Entonces, cuando surja un error, ya tendrás un historial y no tendrás que reproducir el problema de nuevo. Anota el código de respuesta, la etapa del corte y el tiempo de ejecución.

Clasificación automática de errores

En el código puedes crear una función que, según el tipo de excepción y el código de respuesta, asigne de inmediato el error al eslabón correcto. Por ejemplo, ConnectTimeout es el tramo de conexión, ReadTimeout es el tramo de respuesta, ProxyError con túnel es la capa de proxy. Esto acelera la reacción en sistemas automatizados.

Recolección de estadísticas de estabilidad

Lleva métricas: proporción de solicitudes exitosas, proporción de cortes, tiempo de respuesta promedio. Un deterioro brusco de las métricas te avisará del problema antes de que lo enfrentes manualmente.

Consejo: Separa las métricas por eslabones. Cuenta por separado los errores de establecimiento de conexión y los errores en la etapa de respuesta. Así verás de inmediato qué es exactamente lo que se degrada: el acceso al proxy o la comunicación con los sitios.

⚠️ Atención: Al construir un procesamiento automático, no lo conviertas en repeticiones infinitas de la misma solicitud. La lógica de reintentos es un tema grande y aparte con sus propias reglas, relacionada también con el código 429. Tiene su material propio y conviene estudiarla por separado.

FAQ: preguntas frecuentes sobre diagnóstico

¿Cómo entender rápido que la culpa es precisamente del proxy y no de mi código?

Haz esa misma solicitud directamente, sin proxy. Si directamente todo funciona y a través del proxy no, el problema está en la capa de proxy o en su interacción con el sitio. Esto descarta la mitad de las hipótesis en un minuto.

¿Por qué recibo un 407 aunque ingresé la contraseña correcta?

Lo más probable es que la contraseña tenga caracteres especiales que rompen la cadena de conexión. Aplica la codificación URL a la contraseña o transmite los datos mediante un parámetro de autorización aparte, y no en la dirección.

¿El código 502 siempre significa que el proxy está roto?

No. El 502 también puede enviarlo el sitio de destino, si él mismo respondió mal. Haz la verificación cruzada: el mismo sitio directamente y el mismo proxy a un sitio estable. La intersección de los resultados mostrará al culpable.

¿En qué se diferencia connect timeout de read timeout?

Connect timeout es la espera del establecimiento de la conexión. Read timeout es la espera de la respuesta después de que la conexión ya está establecida. Sepáralos en el cliente y verás de inmediato qué etapa se demoró.

¿Por qué tunnel connection failed ocurre solo en HTTPS?

Porque para los sitios protegidos el cliente le pide al proxy construir un túnel con el comando CONNECT. En HTTP normal no existe ese comando. Si el túnel no se construyó, llega este error, y solo es posible en HTTPS.

¿Cómo distinguir un 403 del proxy de un 403 del sitio?

Mira el cuerpo de la respuesta. Una página bien diseñada del sitio significa una prohibición del sitio. Una página técnica o una mención al proxy significan una prohibición del intermediario. Confírmalo con una solicitud directa al sitio.

¿Qué hacer en caso de cortes aleatorios de conexión?

Primero determina la repetibilidad: haz una serie de solicitudes y cuenta la proporción de cortes. Cortes aislados son una inestabilidad tolerable de la red. Cortes masivos son un problema sistémico del proxy o del canal.

¿Cómo compartir de forma segura un registro de curl -v para pedir ayuda?

Tacha obligatoriamente la línea con la autorización del proxy y cualquier encabezado sensible antes de enviarlo. De lo contrario, revelarás tu usuario y contraseña. En caso de duda, cambia los datos comprometidos.

¿Por qué mis solicitudes normales a veces se cortan por timeout?

Probablemente el read timeout está configurado demasiado estricto y cortas respuestas lentas, pero correctas. Aumenta el read timeout con margen y deja el connect timeout pequeño.

¿Dónde leer sobre el código 429 y los reintentos?

El código 429 y las estrategias de reintentos son un tema grande y aparte, no relacionado directamente con los fallos de la capa de proxy. Tiene su material propio; estúdialo por separado del diagnóstico de errores de proxy.

Conclusión: qué dominaste y hacia dónde avanzar

Felicidades. Recorriste el camino desde la confusión ante códigos misteriosos hasta un diagnóstico paso a paso seguro. Recordemos qué hay ahora en tu arsenal.

Resumen de las acciones realizadas. Aprendiste a dividir la cadena en tres eslabones —cliente, proxy y servidor— y a determinar dónde surgió exactamente el error. Resolviste el código 407 y la autorización del proxy, incluidos los traicioneros caracteres especiales en la contraseña. Entendiste la doble naturaleza del 502 y el método de verificación cruzada. Dominaste la separación de connect y read timeouts en el 504. Resolviste el método CONNECT y el error tunnel connection failed en HTTPS. Aprendiste a reconocer las tres causas del 403 del proxy y a diagnosticar los cortes de conexión por etapa. Y, por último, dominaste la habilidad principal: la lectura de la salida de curl -v línea por línea con el trazado preciso de las fronteras entre los eslabones.

Qué hacer después. Consolida la habilidad con la práctica. Cada vez que encuentres un error de proxy, no adivines, sino descompónlo con calma por los eslabones con ayuda de la tabla de diagnóstico. Después de una semana de esa práctica, el diagnóstico se volverá automático.

Hacia dónde desarrollarte. El siguiente paso lógico es estudiar el tema del código 429 y las estrategias correctas de reintentos, al que está dedicado un material aparte. Luego profundiza en la clasificación automática de errores en el código y la recolección de métricas de estabilidad. Esto te convertirá de una persona que apaga incendios en un ingeniero que prevé los problemas con antelación.

Consejo: Guarda esta guía y la tabla de diagnóstico en tus marcadores. Vuelve a ellos con cada nuevo error, hasta que la lógica se convierta en tu segunda naturaleza. La confianza en el diagnóstico llega precisamente mediante la repetición. Todo te saldrá bien.