En algún rincón de Stack Overflow, ahora mismo hay alguien convencido de que Axios "se rompe en silencio" con proxies HTTPS. Es una de las afirmaciones que más se repiten en tutoriales de proxies para Node.js, y no describe la versión actual que probé para esta guía. Monté un entorno de prueba local con orígenes HTTP y HTTPS reales detrás de dos proxies, y Axios 1.19.0 canalizó la solicitud HTTPS mediante una petición CONNECT correcta, en lugar de saltarse el proxy.
Eso no significa que los problemas que la gente cuenta sean inventados. Las versiones antiguas de Axios sí tuvieron errores reales (consulta issue #3384 y issue #4531 para ver los casos), y las versiones recientes de Node incorporan otra ruta de proxy basada en variables de entorno que merece una configuración cuidadosa. Esta guía explica qué funciona realmente hoy en Axios 1.19.0, todas las formas de conectar un proxy a tus solicitudes, un patrón de rotación con interceptores que casi ningún tutorial muestra, y una tabla completa de errores y soluciones para cuando algo se tuerce.
¿Qué es un proxy en Axios y por qué importa en Node.js?
En el contexto de Axios, un proxy no es más que un servidor intermediario entre tu proceso Node y el sitio de destino. Tu solicitud llega primero al proxy, el proxy la reenvía y el destino ve la IP del proxy en lugar de la tuya. Ese es todo el truco.
Los desarrolladores lo usan por varias razones: scrapear sitios que limitan peticiones o bloquean por IP, probar cómo se comporta una app desde otra región, enrutar tráfico a través de una salida corporativa o simplemente mantener la IP de su propio servidor fuera de los logs de acceso de un destino. La configuración oficial de solicitudes de Axios ofrece una opción integrada proxy con campos host, port, protocol y auth; lleva ahí años y es lo primero que muestra cualquier tutorial, incluido este.
Lo que suele pasarse por alto es que esa opción proxy se comporta de forma distinta según si el destino es HTTP o HTTPS, y también según la versión de Axios que estés usando. Esa diferencia es precisamente la razón de ser de esta guía.
Configurar Node.js y Axios (base rápida)
Sáltate esta parte si ya tienes un proyecto en marcha. Si no, te llevará unos dos minutos.
mkdir axios-proxy-demo && cd axios-proxy-demo
npm init -y
npm install axios
Añade "type": "module" a tu package.json si quieres usar imports ESM (yo sí; require() de CommonJS para una demo de proxy ya se siente anticuado). La versión LTS actual de Node es v24.18.0, aunque yo ejecuté las pruebas en v22.22.3 para que los resultados no dependieran de las particularidades del runtime más reciente.
Pon esto en app.js y ejecuta node app.js:
import axios from 'axios';
const res = await axios.get('https://httpbin.org/ip');
console.log(res.data);
Deberías ver tu IP real en la respuesta. Ese es tu punto de partida: cuando el proxy funcione, esta misma solicitud debería devolver la IP del proxy.
Guarda esa respuesta antes de activar el proxy; así tendrás una referencia clara para comparar con la solicitud proxificada en el siguiente paso.
¿Axios realmente admite proxies HTTPS? (aclarando el tema)
Respuesta corta: sí, en la versión estable actual. Axios 1.19.0 documenta el tunneling CONNECT para destinos HTTPS detrás de un proxy HTTP. La API de descargas de npm registró 117.890.039 descargas de Axios entre el 31 de julio y el 6 de agosto de 2026, un indicador algo antiguo pero útil de lo extendido que está el uso de la librería. Cuando accedes a una URL HTTPS a través de un proxy, la versión actual de Axios envía una petición CONNECT para crear un túnel, y el intercambio TLS ocurre de extremo a extremo con el origen real. Lo probé directamente: proxy HTTP local, origen HTTPS local con certificado autofirmado y el contador CONNECT en mi proxy subió exactamente como esperaba.
Entonces, ¿por qué aparece "Axios HTTPS proxy broken" en casi cualquier hilo sobre el tema? Por varias razones, y todas son reales:
- Versiones antiguas de Axios. Los issues de GitHub que la gente enlaza suelen ser de hace años y describen comportamientos específicos de una versión y una configuración que no deberían generalizarse al Axios actual.
- Proxies sin soporte para CONNECT. En ese caso, el túnel falla y Axios debería mostrar un error; captura primero la ruta real y el error antes de asumir que el proxy se ha saltado.
- Confundir la configuración
proxycon algo que no es. La opciónproxysirve para un proxy directo, no como un interruptor genérico de "envía todo por este agente pase lo que pase".
Chromium informó en 2023 que más del 90% de las navegaciones de Chrome en las principales plataformas usaban HTTPS. Es una métrica antigua de Chrome, no un censo actual de toda la web, pero explica por qué el comportamiento frente a destinos HTTPS debe ocupar el centro de este tutorial. Si estás en una versión antigua de Axios, reproduce el problema en la rama actual antes de dar por hecho que un fallo histórico sigue describiendo el comportamiento presente; prueba la actualización en tu propia aplicación antes de desplegarla.
Cuándo sigues queriendo un agente explícito
La configuración nativa proxy está bien para un proxy único, estático y convencional. Pero se queda corta en cuanto necesitas control por solicitud, rotación de proxies o compatibilidad con SOCKS; la opción integrada de Axios simplemente no está pensada para eso. Ahí es donde HttpsProxyAgent realmente aporta valor, y lo verás más abajo. Piensa en la opción nativa como "suficiente para un proxy, un propósito" y en el enfoque basado en agentes como "lo que de verdad quieres en producción".
La ruta de proxy por entorno en Node v24 y v22.21+
Las versiones recientes de Node incluyen un modo de proxy por variables de entorno, activado con NODE_USE_ENV_PROXY=1 o con la bandera --use-env-proxy. Según la documentación de CLI de Node, esto llegó en v24.0.0 y se retroportó a v22.21.0; así que "Node 22+" no es del todo correcto, sino específicamente v22.21.0 y posteriores dentro de esa rama. Si usas una versión anterior de Node 22, esa bandera no existe para ti.
Axios actual ya resuelve HTTP_PROXY, HTTPS_PROXY y NO_PROXY a través de su dependencia proxy-from-env, así que global-agent no hace falta para esta ruta actual de Axios. Cuando también está activo el modo de proxy por entorno de Node, pueden intervenir dos capas en la decisión de enrutado.
La documentación de Axios indica que, en versiones de Node donde el agente expone una propiedad proxyEnv, Axios delega en el manejo de Node en lugar de resolverlo por su cuenta. En la práctica, eso significa que conviene elegir un solo sistema y ceñirse a él:
- Dejar que Node lo gestione: activa la bandera, no configures
proxyen Axios y deja que las variables de entorno hagan el trabajo. - Dejar que Axios lo gestione: no actives la bandera de Node y deja que la resolución propia de Axios sobre variables de entorno entre en acción.
- Control manual total: define explícitamente
proxy: falsey proporciona tu propiohttpsAgent; así evitas por completo los dos sistemas automáticos, que es lo que recomiendo cuando necesitas rotación o lógica por solicitud.
Probé directamente la resolución desde Axios: al definir HTTP_PROXY en el entorno de un proceso hijo, la solicitud se envió a través de mi proxy local, y al añadir una entrada NO_PROXY coincidente, la siguiente solicitud lo omitió correctamente. Así que la ruta por variables de entorno sí funciona de serie ahora; lo que debes vigilar es el escenario de doble modo.
5 formas de conectar un proxy en Axios (comparadas)
Antes de entrar en el código, conviene ver el panorama general. Probé y verifiqué cada una de estas opciones con un entorno local real de proxy, no solo leyendo la documentación.
| Método | Compatibilidad HTTPS | Soporta auth | Control por solicitud | Fácil para rotación | Complejidad |
|---|---|---|---|---|---|
Opción proxy en línea | ✅ (Axios actual) | ✅ | ✅ | ❌ | Baja |
Valores por defecto con axios.create() | ✅ (Axios actual) | ✅ | ❌ (a nivel de instancia) | ❌ | Baja |
Variables de entorno (HTTP_PROXY/HTTPS_PROXY) | ✅ | ✅ | ❌ | ❌ | Baja |
httpsAgent + HttpsProxyAgent | ✅ | ✅ | ✅ | ⚠️ (manual) | Media |
| Interceptor de solicitudes + pool de agentes | ✅ | ✅ | ✅ | ✅ | Media-alta |
Usa la opción en línea para un script rápido que apunte a un solo proxy. Usa axios.create() cuando todas las solicitudes de un módulo deban pasar por el mismo proxy sin repetir configuración. Usa variables de entorno cuando tu equipo de infraestructura ya gestione el enrutado del proxy de forma centralizada y tú solo quieras heredarlo. Recurre a un agente explícito cuando necesites un control que la configuración nativa no ofrece; y pasa al patrón con interceptores en cuanto "control" se convierta en "rotación".

Paso a paso: configuración básica de proxy en Axios
La configuración más simple usa directamente el objeto proxy integrado en la solicitud:
import axios from 'axios';
const res = await axios.get('https://httpbin.org/ip', {
proxy: {
host: '203.0.113.10',
port: 8080,
protocol: 'http',
},
});
console.log(res.data);
Ejecuta esto y deberías ver la IP del proxy en la respuesta, en lugar de la tuya. Si estás probando localmente con un proxy real, esto suele resolverse en menos de un segundo; mucho mejor que configurar manualmente un proxy a nivel de sistema solo para probar una petición, que es justo el tipo de cosa que se come quince minutos que no tienes.
Compara esta respuesta con la referencia inicial. Una prueba correcta debería mostrar la IP pública del proxy en lugar de la IP de origen que guardaste antes.
Usar axios.create() para valores por defecto a nivel de instancia
Si todas las solicitudes de un módulo determinado deben pasar por el mismo proxy, incrústalo en una instancia en lugar de repetir la configuración:
const client = axios.create({
proxy: {
host: '203.0.113.10',
port: 8080,
},
timeout: 15_000,
});
const res = await client.get('https://httpbin.org/ip');
Verifiqué que un override proxy: false en una solicitud individual omite limpiamente el valor por defecto de la instancia; es útil si el 95% de tus llamadas necesitan el proxy pero unas pocas, por ejemplo un ping de comprobación de estado, no deberían usarlo.
Definir el proxy con variables de entorno
Para un enrutado gestionado de forma centralizada —piensa en contenedores Docker o entornos CI donde operaciones ya fija las variables de proxy— no hace falta tocar la configuración de Axios:
export HTTP_PROXY=http://203.0.113.10:8080
export HTTPS_PROXY=http://203.0.113.10:8080
export NO_PROXY=localhost,127.0.0.1
Axios actual lee estas variables sin global-agent. Solo recuerda el límite de versiones de Node mencionado arriba: si NODE_USE_ENV_PROXY también está activo, deja claro quién es el dueño del enrutado y prueba el comportamiento de NO_PROXY en el runtime de producción.
Paso a paso: configuración de proxy HTTPS con httpsAgent (para control real)
Esta es la configuración que yo recomendaría de verdad en cuanto necesites algo más que "un proxy para siempre". Instala el paquete de agente actual:
npm install https-proxy-agent
https-proxy-agent 9.1.0 requiere Node 20 o superior y emite una petición CONNECT correcta a tu proxy antes de canalizar la conexión de destino a través de él.
import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
const agent = new HttpsProxyAgent('http://203.0.113.10:8080');
const client = axios.create({
proxy: false, // evita que la resolución nativa de Axios también intervenga
httpsAgent: agent,
timeout: 15_000,
});
const res = await client.get('https://httpbin.org/ip');
console.log(res.data);
Define proxy: false cuando un agente explícito sea el encargado del enrutado. Eso hace que la configuración sea inequívoca y evita que la resolución nativa o por entorno de Axios compita con el agente suministrado.
Añadir autenticación al proxy
Incorpora las credenciales directamente en la URL del proxy:
const agent = new HttpsProxyAgent('http://myuser:mypassword@203.0.113.10:8080');
Si tu contraseña contiene caracteres especiales —@, : y # suelen dar problemas— codifícalos en porcentaje antes de construir la URL, o construye la cadena con encodeURIComponent() en cada componente. Un @ sin codificar en la contraseña se interpretará como el inicio de la parte del host y acabarás con un error de conexión que aparentemente no tiene nada que ver con la codificación.
Usar proxies SOCKS5 con Axios
Los proxies SOCKS no son compatibles con HttpsProxyAgent; necesitas otro agente para ese protocolo:
npm install socks-proxy-agent
import { SocksProxyAgent } from 'socks-proxy-agent';
const agent = new SocksProxyAgent('socks5://myuser:mypass@203.0.113.10:1080');
const client = axios.create({
proxy: false,
httpsAgent: agent,
});
socks-proxy-agent 10.1.0 también requiere Node 20+. SOCKS5 merece la pena cuando trabajas con redes corporativas que solo exponen una puerta de enlace SOCKS, o con proveedores de proxy que ofrecen compatibilidad de protocolo más flexible que los simples proxies HTTP.
Rotar proxies con interceptores de solicitudes en Axios
Elegir un proxy aleatorio dentro del propio código de llamada funciona bien para un script puntual. Se desmorona en cuanto haces cientos de solicitudes, porque no hay un lugar central que controle qué proxies están caídos, no hay lógica de reintento y la selección del proxy acaba copiada por todas partes. El sistema de interceptores de Axios da a esa lógica un único sitio testable; ninguno de los cinco tutoriales competidores que revisé en el SERP de este artículo usaba este patrón.

Construir un pool de proxies
import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
class ProxyPool {
private agents: HttpsProxyAgent<string>[];
private index = 0;
constructor(proxyUrls: string[]) {
this.agents = proxyUrls.map((url) => new HttpsProxyAgent(url));
}
next(): HttpsProxyAgent<string> {
const agent = this.agents[this.index];
this.index = (this.index + 1) % this.agents.length;
return agent;
}
}
const pool = new ProxyPool([
'http://user:pass@proxy1.example.com:8080',
'http://user:pass@proxy2.example.com:8080',
]);
const client = axios.create({ timeout: 15_000 });
client.interceptors.request.use((config: InternalAxiosRequestConfig) => {
config.proxy = false;
config.httpsAgent = pool.next();
return config;
});
Probé esto con dos proxies locales y confirmé que las solicitudes alternaban correctamente: proxy A, luego proxy B, luego otra vez A. Ten en cuenta que Axios ejecuta los interceptores de solicitud en orden inverso al que se añaden, así que si tienes otros interceptores (cabeceras de autenticación, logs), el orden importa más de lo que parece.
Añadir un interceptor de respuesta con límites de reintento
Aquí es donde la mayoría de scripts caseros de rotación empiezan a fallar. Reintentar a ciegas cualquier error, con un pool ilimitado, puede convertir una petición mala en un efecto dominó —sobre todo en métodos no idempotentes como POST, donde reintentar podría duplicar una acción que no querías duplicar.
type RetryableConfig = InternalAxiosRequestConfig & {
__proxyRetryCount?: number;
};
client.interceptors.response.use(
undefined,
async (error: AxiosError) => {
const config = error.config as RetryableConfig | undefined;
if (!config) throw error;
const method = String(config.method ?? 'get').toUpperCase();
config.__proxyRetryCount ??= 0;
if (method !== 'GET' || config.__proxyRetryCount >= 1) throw error;
config.__proxyRetryCount += 1;
config.proxy = false;
config.httpsAgent = pool.next();
return client.request(config);
}
);
Lo probé contra un proxy deliberadamente roto y confirmé que solo se disparaba un reintento en el agente alternativo: sin bucle infinito, sin reintento en una petición POST. Ese es el límite que quieres: una política de reintento honesta sobre qué solicitudes se pueden repetir, no un truco de "prueba otra vez hasta que funcione".

Tabla de diagnóstico de errores: cada fallo y su solución
Guarda esto en favoritos. Estos son los errores que realmente aparecen en issues de GitHub de Axios y en hilos de Stack Overflow, no los hipotéticos.
| Error / Síntoma | Causa probable | Solución |
|---|---|---|
ECONNREFUSED | Host/puerto incorrectos, o el servidor proxy está caído | Verifica con curl -x http://host:port target-url antes de tocar el código de Axios |
407 Proxy Authentication Required | Credenciales ausentes o incorrectas | Añade auth: { username, password } a la configuración proxy, o incorpora las credenciales en la URL de HttpsProxyAgent |
403 Forbidden | El origen o el WAF rechazó la solicitud o la IP del proxy | Revisa la política de acceso del sitio, la autenticación y la tasa de peticiones; no interpretes una cabecera distinta o una IP diferente como permiso para saltarte restricciones |
| La respuesta muestra tu IP real | NO_PROXY, proxy:false, un agente directo explícito o una configuración histórica/específica de versión pueden estar evitando el proxy | Comprueba qué capa controla el enrutado; verifica la ruta con un endpoint de IP controlado y un agente explícito si hace falta |
ETIMEDOUT | El tiempo de conexión o de respuesta superó el timeout configurado | Mide dónde se va el tiempo; ajusta el timeout solo si la carga de trabajo lo justifica, si no, reemplaza o enfría la ruta problemática |
ECONNRESET a mitad de respuesta | El proxy, la red o el origen cerraron la conexión | Registra en qué salto falla; reintenta solo solicitudes seguras de reproducir con un presupuesto finito |
502 Bad Gateway detrás de Nginx | proxy_pass de Nginx mal configurado, o el timeout de Axios no coincide con el de Nginx | Revisa proxy_connect_timeout y proxy_read_timeout (ambos tienen 60s por defecto) y alínalos con el timeout de Axios |
ERR_TLS_CERT_ALTNAME_INVALID | Tipo de agente incorrecto para el destino, o certificado autofirmado | Confirma que usas el agente correcto para el protocolo; usa rejectUnauthorized: false solo en pruebas locales, nunca en producción |
Lista rápida de depuración
Cuando algo falla y no sabes por qué, sigue este orden:
- Prueba el proxy directamente con
curl -x http://host:port https://your-target.com. Si falla, investiga la conectividad del proxy, la autenticación y el destino antes de cambiar Axios. Si funciona, la ruta de Axios todavía necesita verificación aparte. - Confirma qué versiones de Axios y Node estás ejecutando realmente, y compara los informes históricos con la misma versión/configuración antes de aplicar sus soluciones.
- Averigua qué sistema está resolviendo el proxy: la configuración nativa de Axios, la resolución de variables de entorno de Axios, el modo de proxy por entorno integrado de Node o un agente explícito. Nunca dejes que más de uno controle la misma solicitud.
- Revisa
NO_PROXYpor coincidencias accidentales de hostnames. - Si usas un agente explícito, confirma que
proxy: falseesté configurado para que Axios no intente gestionarlo dos veces.
Cuándo saltarte por completo el trabajo artesanal del proxy
Todo lo anterior es realmente útil si tu objetivo real es enrutar tráfico arbitrario: pruebas de redes corporativas, pruebas geográficas de una app o salida de red controlada. Pero muchos desarrolladores llegan a "cómo configurar un proxy en Axios" porque en realidad quieren datos de una web, y el proxy solo es un medio para ese fin.
Si ese es tu caso, merece la pena preguntarse si de verdad necesitas un proxy o si lo que necesitas es una API de scraping que se encargue de la infraestructura por ti. La API Open de Thunderbit recibe una URL y un esquema y devuelve JSON estructurado: sin análisis de HTML en bruto, sin bibliotecas de agentes y sin un pool de proxies que vigilar. El endpoint /extract gestiona páginas renderizadas con JS, medidas antibot y CAPTCHAs del lado del servidor, y existe además un endpoint más ligero /distill que simplemente convierte una página a Markdown limpio si eso es todo lo que necesitas. También hay un servidor MCP que expone herramientas como thunderbit_extract y thunderbit_suggest_fields, para que asistentes de codificación como Claude o Cursor puedan extraer datos estructurados durante la tarea sin tocar ninguna configuración de proxy, además de un CLI para terminal y flujos de trabajo en CI.
| Aspecto | DIY con Axios + proxies | API/MCP/CLI de Thunderbit |
|---|---|---|
| Obtención y rotación de proxies | La gestionas tú | Se gestiona en el servidor |
| Desafíos de navegador y acceso | Tú operas la capa de navegador/red | Lo gestiona el servicio dentro de sus capacidades documentadas |
| Páginas renderizadas con JS | Necesitas un navegador headless | renderMode: full |
| Formato de salida | HTML bruto → lo analizas tú | JSON estructurado mediante esquema |
| Mantenimiento cuando cambian los sitios | Tú mantienes parsing/selectores | La capa de extracción gestionada reduce parte del mantenimiento en la aplicación |
La lectura honesta es esta: si necesitas enrutar tráfico para pruebas o redes corporativas, nada de esto sustituye a Axios y a una configuración de proxy. Si tu entregable es datos web estructurados, un enfoque basado primero en API puede reducir el código de proxy, navegador y parsing que tu aplicación tiene que mantener. En el momento de la consulta, el 7 de agosto de 2026, la documentación de límites de la API de Thunderbit mostraba su plan Free con 10 solicitudes por minuto y 2 solicitudes concurrentes. Tómalos como límites de API sujetos a cambios y vuelve a revisar la página antes de apoyarte en ellos en producción.
Conclusión
La lección principal va contra lo que dicen muchos tutoriales antiguos: la Axios actual documenta y, en la prueba local registrada, usó correctamente el tunneling CONNECT para un destino HTTPS. Los fallos históricos siguen importando, pero necesitan contexto de versión y configuración. La configuración nativa es un buen punto de partida con baja complejidad; cuando necesitas control por solicitud, compatibilidad con SOCKS o rotación, un HttpsProxyAgent explícito (o SocksProxyAgent) junto con proxy: false te da una propiedad mucho más clara. Y si en producción vas a rotar entre varios proxies, los interceptores de solicitud y respuesta te ofrecen un lugar centralizado y testeable para hacerlo; solo asegúrate de que tu lógica de reintento tenga un guardarraíl y de que solo vuelva a ejecutar solicitudes que realmente sean seguras de repetir.
Guarda la tabla de diagnóstico de arriba para la próxima vez que una configuración de proxy te devuelva un error críptico a las 2 de la madrugada. Y si te das cuenta de que pasas más tiempo depurando la capa del proxy que usando realmente los datos que querías obtener, quizá merezca la pena comprobar si una herramienta de extracción basada primero en API resuelve el problema real antes de que la infraestructura llegue a hacerlo.
Preguntas frecuentes
¿Axios admite proxies HTTPS de forma nativa? Sí, en la Axios actual para un proxy HTTP convencional: la documentación vigente describe tunneling CONNECT para destinos HTTPS, y Axios 1.19.0 pasó esa ruta en la prueba local registrada. Las versiones históricas y determinadas configuraciones de proxy sí produjeron fallos reales, así que verifica la versión exacta y el proxy concreto en lugar de asumir éxito o fracaso universal.
¿Cómo roto proxies en Axios?
Usa un interceptor de solicitudes para asignar un httpsAgent distinto desde un pool de proxies antes de cada petición, y combínalo con un interceptor de respuestas que reintente las solicitudes fallidas usando otro proxy. Mantén la lógica de reintento acotada —un solo reintento y solo para métodos idempotentes como GET— para no repetir accidentalmente una solicitud que no debería repetirse.
¿Por qué mi proxy de Axios muestra mi IP real?
Comprueba si NO_PROXY, proxy:false, un agente directo explícito o un enrutado específico del despliegue están evitando el proxy. Registra las versiones de Axios/Node y prueba el proxy de forma independiente con cURL. Si necesitas un enrutado inequívoco por solicitud, usa HttpsProxyAgent con proxy:false y verifica la IP observada en un endpoint controlado.
¿Puedo usar proxies SOCKS5 con Axios?
Sí, mediante el paquete socks-proxy-agent. Crea una instancia de SocksProxyAgent con tu URL SOCKS y pásala como httpsAgent en la configuración de Axios; solo asegúrate de no pasar también HttpsProxyAgent, porque ambos protocolos usan tipos de agente distintos.
¿Cuál es la diferencia entre la opción proxy y httpsAgent en Axios?
La opción proxy es la configuración integrada de Axios para un único proxy estático y funciona bien en casos sencillos en las versiones actuales. httpsAgent acepta un agente personalizado de Node.js —como HttpsProxyAgent o SocksProxyAgent— y te da control directo por solicitud sobre enrutado, autenticación y rotación, algo para lo que la opción nativa nunca fue diseñada.


