Códigos de Salida de curl (Exit Codes 1-99): Referencia y Solución

Referencia de exit codes y return codes de curl (1-99): busca cualquier código, como el 22, el 3, el 28 o el 52, y encuentra su significado, causas comunes y la solución exacta. Alternativa rápida a la documentación oficial para depurar CI/CD, cron y scripts.

Tabla de Referencia de Exit Codes de curl

Código	Nombre de la Constante	Significado	Causas Comunes
Errores de Conexión / Inicialización
1	CURLE_UNSUPPORTED_PROTOCOL	Indica que curl no admite el protocolo especificado en la URL.	Ocurre al usar un binario de curl compilado sin ese protocolo habilitado (por ejemplo, gopher, ldap), o por un error tipográfico en el esquema de la URL.
2	CURLE_FAILED_INIT	Indica que la inicialización interna de curl falló.	Un fallo de inicialización de bajo nivel poco frecuente, normalmente causado por memoria insuficiente o un entorno anómalo.
3	CURLE_URL_MALFORMAT	Indica que la URL especificada está mal formada y curl no puede analizarla.	Ocurre cuando a la URL le falta el esquema (por ejemplo, http://) o contiene caracteres no válidos.
5	CURLE_COULDNT_RESOLVE_PROXY	Indica que curl no pudo resolver el nombre de host del servidor proxy especificado.	Causado por un error tipográfico en el nombre de host pasado a --proxy, o un fallo de DNS específico del proxy.
6	CURLE_COULDNT_RESOLVE_HOST	Indica que curl no pudo resolver (DNS) el nombre de host del servidor de destino.	Normalmente causado por un error tipográfico en el nombre de dominio, una caída del servidor DNS, o la ejecución en un entorno sin conexión.
7	CURLE_COULDNT_CONNECT	Indica que el nombre de host se resolvió, pero curl no pudo establecer una conexión TCP con el servidor.	Ocurre por un número de puerto incorrecto, un firewall que bloquea la conexión, o porque el servidor está caído.
8	CURLE_WEIRD_SERVER_REPLY	Indica que curl recibió una respuesta inesperada del servidor que no pudo interpretar.	Común cuando un servidor FTP devuelve una respuesta no estándar, o cuando curl se conecta accidentalmente a un servidor que usa otro protocolo.
9	CURLE_REMOTE_ACCESS_DENIED	Indica que curl se conectó al servidor pero se le denegó el acceso.	Ocurre por permisos insuficientes en un directorio FTP, o cuando el servidor aplica una restricción de IP.
Errores de Transferencia de Datos
18	CURLE_PARTIAL_FILE	Indica que la transferencia se interrumpió antes de completarse, por lo que solo se recibió parte del archivo.	Ocurre por una breve interrupción de red, o cuando el servidor cierra la conexión antes de alcanzar el Content-Length anunciado.
23	CURLE_WRITE_ERROR	Indica que curl no pudo escribir datos en el disco local o en el destino del callback.	Ocurre cuando el disco está lleno, o curl carece de permiso de escritura para el archivo de salida.
26	CURLE_READ_ERROR	Indica que curl no pudo leer el archivo local que se iba a subir.	Ocurre cuando el archivo especificado con -T/--upload-file no existe, o curl carece de permiso de lectura sobre él.
52	CURLE_GOT_NOTHING	Indica que curl se conectó al servidor pero no recibió ninguna respuesta en absoluto.	Normalmente causado porque el proceso del servidor falla a mitad de la solicitud, o por una mala configuración que devuelve una respuesta vacía.
55	CURLE_SEND_ERROR	Indica que curl no pudo enviar datos por la red.	Ocurre cuando el lado remoto se desconecta inmediatamente después de establecerse la conexión, o por un problema en la interfaz de red local.
56	CURLE_RECV_ERROR	Indica que curl no pudo recibir datos de la red.	Se ve con frecuencia cuando el lado remoto reinicia inesperadamente la conexión durante la transferencia (Connection reset by peer).
63	CURLE_FILESIZE_EXCEEDED	Indica que el tamaño del archivo superó el límite establecido con --max-filesize.	Ocurre cuando la respuesta resulta ser más grande de lo esperado y alcanza el límite de seguridad configurado.
78	CURLE_REMOTE_FILE_NOT_FOUND	Indica que el archivo especificado no existe en el servidor remoto (por ejemplo, FTP).	Ocurre por un error tipográfico en la ruta FTP, o porque el archivo objetivo ya se eliminó o se movió.
Errores de Certificado SSL/TLS
35	CURLE_SSL_CONNECT_ERROR	Indica que ocurrió un problema durante el handshake SSL/TLS, impidiendo establecer la conexión.	Suele deberse a una incompatibilidad entre las versiones de TLS o los conjuntos de cifrado admitidos por el servidor y el cliente.
51	CURLE_PEER_FAILED_VERIFICATION	Indica que la verificación del certificado del servidor falló (por ejemplo, el certificado no coincide con el nombre de host).	Ocurre al acceder a un certificado autofirmado, o cuando el Common Name/SAN del certificado difiere del nombre de host de destino.
58	CURLE_SSL_CERTPROBLEM	Indica un problema con el certificado de cliente especificado localmente.	Normalmente causado por un formato inválido en el archivo de certificado pasado con --cert, o una frase de contraseña incorrecta.
60	CURLE_SSL_CACERT	Indica que curl no pudo verificar la cadena de certificados de la CA usada para validar el certificado del servidor.	Ocurre cuando el paquete de certificados de la CA está desactualizado, o una CA autofirmada (como la de un proxy corporativo) no está registrada en el almacén de confianza. -k/--insecure es una solución temporal, pero no se recomienda para producción.
Errores de HTTP / Autenticación
22	CURLE_HTTP_RETURNED_ERROR	Indica que, con la opción -f/--fail especificada, la respuesta HTTP devolvió un estado de error igual o superior a 400.	Se provoca intencionadamente en scripts de CI/CD que usan curl -f para detectar como fallo un estado de error de la API.
67	CURLE_LOGIN_DENIED	Indica que el inicio de sesión (autenticación) en el servidor fue rechazado.	Normalmente causado por un nombre de usuario o contraseña incorrectos, o un bloqueo de cuenta en protocolos como FTP/SMTP.
Otros
27	CURLE_OUT_OF_MEMORY	Indica que curl no pudo asignar memoria durante la ejecución.	Una situación poco frecuente, como intentar procesar un archivo enorme en un sistema con memoria limitada.
28	CURLE_OPERATION_TIMEDOUT	Indica que la operación no se completó dentro del límite de tiempo establecido con --connect-timeout/--max-time, etc.	Uno de los errores más frecuentes en CI, causado por una respuesta lenta del servidor, latencia de red, o un valor de tiempo de espera demasiado corto.
47	CURLE_TOO_MANY_REDIRECTS	Indica que el número de redirecciones superó el límite establecido con --max-redirs.	Ocurre por un bucle de redirecciones (301/302 redirigiendo circularmente), o una cadena de redirecciones legítima más larga que el límite predeterminado (50).

¿Qué es un exit code de curl?

Un exit code de curl es el número que curl devuelve a la shell (consultable con $?) al finalizar su ejecución, indicando si la solicitud tuvo éxito y, si no, por qué. A diferencia del código de estado HTTP que devuelve el servidor, el exit code describe el resultado del propio comando curl: un fallo de DNS, un timeout de conexión, un error de negociación SSL, etc.

Esta herramienta permite buscar cualquier exit code (1-99) para ver su significado y las causas más comunes, o filtrar la tabla de referencia completa por código, nombre de constante o palabra clave. Está pensada para depurar fallos de curl en pipelines de CI/CD, tareas cron o scripts de shell que llaman a APIs o descargan archivos.

Cómo usar esta herramienta

Introduce el número de exit code Escribe el código que obtuviste con echo $? tras un comando curl fallido en el cuadro de búsqueda.
Consulta el significado y las causas comunes La herramienta muestra qué indica el código y en qué situaciones suele producirse.
Filtra la tabla completa Si no conoces el número exacto, filtra la tabla de referencia por palabra clave en su lugar.
Revisa la solución sugerida Usa las causas comunes como punto de partida para aplicar la corrección adecuada en tu script o entorno.

Consejos para aprovecharla mejor

Puedes comprobar el exit code inmediatamente con $? (Bash) o %errorlevel% (Windows). En scripts de shell, una ramificación como curl ... || echo "failed with $?" resulta muy práctica.
El 28 (tiempo de espera agotado) y el 7 (fallo de conexión) suelen confundirse, pero el 28 ocurre cuando la respuesta es lenta después de establecer la conexión, mientras que el 7 ocurre cuando la propia conexión TCP nunca llegó a establecerse.
Si obtienes un 60 (error de certificado de CA), no lo evites simplemente con -k/--insecure: primero comprueba si el paquete de certificados de CA (ca-certificates) está actualizado. Usar -k de forma habitual en producción aumenta el riesgo de ataques de intermediario (man-in-the-middle).
El 22 (error HTTP) solo ocurre si añades la opción -f/--fail. Sin ella, curl devuelve el exit code 0 (éxito) incluso ante una respuesta 404 o 500, así que añade siempre -f si quieres que CI detecte los fallos.

Casos de Uso

Depurar un paso fallido de un pipeline de CI/CD

Identifica rápidamente por qué falló un paso de despliegue o health-check basado en curl consultando el exit code del log de build.

Diagnosticar una tarea cron que falla en silencio

Las tareas cron casi nunca muestran salida, así que revisar el exit code registrado suele ser la vía más rápida hacia la causa raíz.

Escribir manejo de errores robusto en scripts

Consulta qué códigos indican un problema de red que admite reintentos frente a un error permanente para ramificar la lógica del script.

Análisis posterior a un incidente (postmortem)

Confirma con exactitud qué tipo de fallo (DNS, TLS, timeout) ocurrió al revisar los registros tras una interrupción del servicio.

Aprender los fundamentos de curl y redes

Usa la tabla para entender de forma sistemática en qué fase de una transferencia (resolución, conexión, TLS, transferencia) puede fallar cada paso.

Glosario

Exit code: Número que un programa devuelve a la shell al finalizar. 0 significa éxito; curl usa 1-99 para indicar tipos específicos de fallo.
CURLcode: El enum interno de libcurl que define cada tipo de error. Los exit codes de la línea de comandos de curl se corresponden directamente con este enum.
libcurl: La librería en C que implementa la lógica central de transferencia de curl. La herramienta de línea de comandos curl es solo un envoltorio ligero sobre ella.
Opción --fail / -f: Opción de curl que hace que las respuestas de error HTTP (400 o superior) produzcan el exit code 22 en lugar del exit code 0 por defecto.
Timeout frente a conexión rechazada: El timeout (28) significa que no llegó respuesta a tiempo; el rechazo/fallo de conexión (7) significa que no se pudo establecer la propia conexión TCP.
Resolución DNS: El proceso de convertir un nombre de host en una dirección IP. Si falla, curl devuelve el exit code 6.
Negociación SSL/TLS: El proceso mediante el cual cliente y servidor establecen una conexión cifrada. Los problemas en esta fase suelen producir los exit codes 35, 51, 58 o 60.

Preguntas Frecuentes

Justo después de ejecutar el comando curl, compruébalo con echo $? en Bash/Zsh, echo %errorlevel% en el símbolo del sistema de Windows, o $LASTEXITCODE en PowerShell.

Primero revisa la configuración de --connect-timeout y --max-time, y auméntala si es necesario. Si el servidor responde lentamente de forma constante, comprueba también su carga y la ruta de red (proxies, VPN, etc.).

No, son cosas diferentes. Los códigos de estado HTTP (como 404 o 500) son respuestas a nivel de protocolo devueltas por el servidor, mientras que los exit codes de curl indican el resultado de la propia ejecución del comando curl (fallo de conexión, tiempo de espera, etc.). Por defecto, curl trata los errores HTTP como exit code 0 (éxito), así que hay que tener cuidado de no confundir ambos conceptos.

Añade la opción curl -f (--fail) para que curl devuelva el exit code 22 siempre que la respuesta HTTP sea igual o superior a 400. Sin ella, obtener con éxito una página de error seguirá dando como resultado un exit code 0.

El 6 (COULDNT_RESOLVE_HOST) es un error en la fase de DNS, cuando no se puede resolver el nombre de host a una dirección IP. El 7 (COULDNT_CONNECT) es un error en el que la resolución de nombres tuvo éxito, pero no se pudo establecer la conexión TCP con esa dirección IP.

A propósito — El sistema de exit codes de curl

curl es una herramienta de línea de comandos cuyo desarrollo comenzó en 1996 de la mano de Daniel Stenberg, originalmente bajo el nombre "httpget". Hoy en día curl viene incluido de serie en prácticamente todas las distribuciones de Linux, en macOS y en Windows 10 y versiones posteriores, lo que la convierte en una de las herramientas más fundamentales para los desarrolladores web.

El sistema de exit codes se corresponde directamente con el enum de errores interno de libcurl, CURLcode, y se define con una numeración secuencial que comienza en `CURLE_OK` (éxito, exit code 0). Los huecos en la numeración existen porque algunos códigos de error se marcaron como obsoletos o se fusionaron durante el desarrollo.

Curiosamente, los exit codes de curl forman un sistema propio e independiente de la convención general de POSIX (0 = éxito, 1 = error general). Esto significa que, al gestionar los exit codes de varias herramientas en un script de shell, es necesario consultar el manual de cada una por separado para entender su significado.

Ver todas las curiosidades