Red
Referencia de Códigos de Salida de curl
Referencia completa de los exit code (códigos de salida) del comando curl: significados, causas comunes y soluciones para desarrolladores que depuran pipelines de CI/CD y scripts de shell. Incluye una herramienta de búsqueda: introduce un número de código para ver los detalles al instante.
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). |
Consejos
- Puedes comprobar el exit code inmediatamente con
$?(Bash) o%errorlevel%(Windows). En scripts de shell, una ramificación comocurl ... || 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.
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.