Códigos de error de curl: Referencia completa

Tabla de referencia rápida

Error 6: No se pudo resolver el host

Qué significa

Tu terminal muestra curl: (6) Could not resolve host. curl no pudo resolver el nombre de host a una dirección IP — la búsqueda DNS falló antes de que se intentara cualquier conexión.

Causas

Las causas más comunes son: un error tipográfico en el nombre de host (por ejemplo, curl https://apiexample.com en lugar de api.example.com), problemas con el servidor DNS (tu DNS configurado está caído o inaccesible), sin conexión de red (Wi-Fi desconectado, VPN no conectada), o el dominio genuinamente no existe.

Cómo solucionarlo

Primero, verifica que la URL sea correcta. Luego prueba la resolución DNS directamente: nslookup api.example.com o dig api.example.com. Si el DNS falla, prueba un servidor DNS diferente: curl --dns-servers 8.8.8.8 https://api.example.com. Revisa tu /etc/resolv.conf o la configuración de red. Si estás detrás de una VPN corporativa, asegúrate de que el DNS interno pueda resolver el host.

$ curl https://api.exmple.com/users

Error 7: Fallo al conectar

Qué significa

Tu terminal muestra curl: (7) Failed to connect to host port: Connection refused. curl resolvió el nombre de host pero no pudo establecer una conexión TCP con el servidor — la conexión fue rechazada activamente o se agotó el tiempo a nivel TCP.

Causas

Las causas comunes incluyen: el servidor está caído o no está ejecutándose, un firewall está bloqueando el puerto (revisa tanto el firewall local como el del servidor), el puerto es incorrecto (por ejemplo, el servicio corre en 8080 pero te estás conectando al 443), o la cola de conexiones del servidor está llena bajo alta carga.

Cómo solucionarlo

Verifica que el servidor esté ejecutándose: ping api.example.com y telnet api.example.com 443. Comprueba si el puerto correcto está abierto: nmap -p 443 api.example.com. Desactiva temporalmente el firewall local para probar. Si usas Docker, asegúrate de que el puerto del contenedor esté publicado. Prueba con modo detallado: curl -v https://api.example.com para ver exactamente dónde falla la conexión.

$ curl https://localhost:8080/api

Error 22: HTTP devolvió un error

Qué significa

Tu terminal muestra curl: (22) The requested URL returned error. El servidor devolvió un código de estado HTTP de error (4xx o 5xx) y curl fue invocado con -f o --fail, lo que le indica a curl que trate los errores HTTP como fallos.

Causas

El error es provocado por códigos de estado HTTP como 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found) o 500 (Internal Server Error) — pero solo cuando se usa --fail. Sin --fail, curl sale con código 0 incluso en errores HTTP. Causas comunes: URL incorrecta, falta de autenticación, permisos insuficientes o errores del lado del servidor.

Cómo solucionarlo

Ejecuta curl sin --fail para ver el cuerpo completo de la respuesta — a menudo contiene el mensaje de error real. Verifica el código de estado HTTP: curl -w "%{http_code}" -o /dev/null -s URL. Para 401/403: verifica tu token de autenticación o clave de API. Para 404: revisa la ruta de la URL. Para 500: el problema está en el servidor.

$ curl --fail https://api.example.com/nonexistent

Error 28: Tiempo de operación agotado

Qué significa

Tu terminal muestra curl: (28) Operation timed out o curl: (28) Connection timed out. La operación tardó más del tiempo permitido. Este es el error de curl más común — puede ocurrir durante la resolución DNS, la conexión TCP, el handshake SSL o la transferencia de datos.

Causas

Las causas típicas incluyen: servidor lento o sobrecargado que no responde a tiempo, congestión de red o pérdida de paquetes, firewall descartando paquetes silenciosamente (sin rechazo, solo silencio), valores de timeout demasiado estrictos establecidos con --connect-timeout o --max-time, o una mala configuración del proxy causando retrasos.

Cómo solucionarlo

Aumenta el tiempo de espera: curl --connect-timeout 30 --max-time 120 URL. Usa el modo detallado para ver dónde se detiene: curl -v URL. Prueba la latencia de red: ping api.example.com y traceroute api.example.com. Si estás detrás de un proxy, intenta omitirlo: curl --noproxy '*' URL. Para transferencias de archivos grandes, considera usar --retry 3 con --retry-delay 5.

$ curl --connect-timeout 5 https://slow-api.example.com/data

Error 35: Error de conexión SSL

Qué significa

Tu terminal muestra curl: (35) SSL connect error. El handshake SSL/TLS falló — curl no pudo establecer una conexión segura con el servidor.

Causas

Causas comunes: incompatibilidad de versión TLS (el servidor requiere TLS 1.3 pero tu curl solo soporta hasta TLS 1.2), incompatibilidad de suite de cifrado, mala configuración SSL del servidor (certificado expirado presentado durante el handshake, cadena incompleta), el servidor no soporta realmente HTTPS en el puerto dado, o un proxy o firewall está interceptando la conexión SSL (MITM).

Cómo solucionarlo

Fuerza una versión específica de TLS: curl --tlsv1.2 URL o curl --tlsv1.3 URL. Comprueba lo que soporta el servidor: openssl s_client -connect api.example.com:443. Actualiza curl y OpenSSL a las últimas versiones. Si el servidor usa un certificado autofirmado, esto es normalmente el error 60 — el error 35 típicamente indica un fallo de handshake a nivel de protocolo.

$ curl https://legacy-server.example.com/api

Error 56: Fallo de recepción — La conexión fue restablecida

Qué significa

Tu terminal muestra curl: (56) Recv failure: Connection reset by peer. La conexión se estableció exitosamente, pero la recepción de datos falló — el servidor cerró o restableció la conexión inesperadamente durante la transferencia.

Causas

Esto sucede a menudo cuando: el servidor se cae o reinicia durante la transferencia, un balanceador de carga o proxy corta la conexión (timeout de inactividad, solicitud demasiado grande), un firewall termina conexiones de larga duración, el servidor tiene un timeout de keep-alive más corto de lo esperado, o hay una interrupción de red entre cliente y servidor.

Cómo solucionarlo

Intenta la solicitud de nuevo — los problemas transitorios de red son la causa más común. Usa el modo detallado: curl -v URL para ver el punto exacto del fallo. Si el error ocurre durante cargas grandes, prueba la transferencia por fragmentos: curl -H "Transfer-Encoding: chunked" URL. Para operaciones Git que muestran RPC failed; curl 56, aumenta el buffer: git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

Error 60: Problema con el certificado SSL

Qué significa

Tu terminal muestra curl: (60) SSL certificate problem: unable to get local issuer certificate. curl no pudo verificar el certificado SSL del servidor contra su paquete de CA (Autoridad de Certificación). El handshake TLS se completó a nivel de protocolo, pero la validación del certificado falló.

Causas

Las causas más comunes: el servidor usa un certificado autofirmado, el certificado ha expirado, la cadena de certificados está incompleta (faltan certificados intermedios), el paquete de CA de curl está desactualizado (común en sistemas antiguos o en contenedores Docker), o el Common Name / SAN del certificado no coincide con el nombre de host solicitado.

Cómo solucionarlo

Actualiza el paquete de CA: curl --cacert /path/to/cacert.pem URL. Descarga un paquete actualizado desde https://curl.se/ca/cacert.pem. Para diagnosticar: openssl s_client -connect api.example.com:443 -showcerts. Para certificados autofirmados en desarrollo, usa curl -k URL (nunca en producción — desactiva toda la verificación de certificados). En Docker, instala el paquete ca-certificates.

$ curl https://self-signed.example.com/api

Otros códigos de error

Cómo depurar errores de curl

Cuando curl falla, estos tres flags te ayudan a identificar rápidamente la causa raíz — desde la resolución DNS hasta el handshake SSL y la carga útil de la respuesta.

1. 1

   Activar salida detallada

   Ejecuta curl -v URL para ver el ciclo completo de solicitud/respuesta: resolución DNS, conexión TCP, handshake TLS, encabezados de solicitud enviados y encabezados de respuesta recibidos. Este es el flag de depuración más útil.

2. 2

   Verificar el código de estado HTTP

   Ejecuta curl -o /dev/null -s -w "%{http_code}" URL para obtener solo el código de estado HTTP (200, 404, 500, etc.) sin el cuerpo de la respuesta. Útil para verificaciones rápidas de estado y scripts.

3. 3

   Mostrar errores silenciosamente

   Ejecuta curl -sS URL para suprimir la barra de progreso (-s) pero seguir mostrando errores (-S). Perfecto para scripts donde quieres una salida limpia pero necesitas capturar fallos.

Preguntas frecuentes