Explorar guías rápidas · APIs

Tecnología: APIsCategoría: Pruebas HTTP y de APIsNivel: IntermedioActualizado

Referencia rápida de cURL

Usa cURL para probar y diagnosticar APIs HTTP con patrones prácticos para métodos, encabezados, autenticación, cuerpos JSON, archivos, redirecciones, tiempos de espera, reintentos, inspección de respuestas y diagnóstico seguro en producción.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Solicitud GET simple
  5. 2. Enviar un método HTTP explícito
  6. 3. Añadir un encabezado Accept
  7. 4. Enviar JSON
  8. 5. Usar --json para solicitudes JSON
  9. 6. Enviar JSON desde un archivo
  10. 7. Enviar los bytes sin procesar del cuerpo de la solicitud desde un archivo
  11. 8. Añadir un token Bearer
  12. 9. Autenticación Basic
  13. 10. Clave de API en un encabezado
  14. 11. Clave de API en la cadena de consulta
  15. 12. Añadir varios encabezados
  16. 13. Enviar parámetros de consulta de forma segura
  17. 14. Enviar datos de formulario codificados como URL
  18. 15. Enviar datos de formulario multipart
  19. 16. Subir un archivo directamente
  20. 17. Descargar un archivo con un nombre concreto
  21. 18. Conservar el nombre de archivo proporcionado por el servidor
  22. 19. Seguir redirecciones
  23. 20. Mostrar los encabezados y el cuerpo de la respuesta
  24. 21. Guardar los encabezados de la respuesta por separado
  25. 22. Mostrar solo los encabezados de la respuesta
  26. 23. Imprimir solo el código de estado HTTP
  27. 24. Imprimir el estado y los tiempos
  28. 25. Imprimir los tiempos de DNS y TLS
  29. 26. Fallar ante errores HTTP conservando una salida útil
  30. 27. Usar una salida apta para scripts
  31. 28. Establecer un tiempo de espera de conexión
  32. 29. Establecer un tiempo de espera global
  33. 30. Reintentar fallos transitorios
  34. 31. Ten cuidado al reintentar POST/PATCH/DELETE
  35. 32. Usar una clave de idempotencia cuando la API la admita
  36. 33. Ampliar los reintentos solo cuando esté justificado
  37. 34. Inspeccionar el detalle verboso de la solicitud y la respuesta
  38. 35. Nunca pegues la salida verbosa en público sin revisarla
  39. 36. Usar la salida de traza para depurar el protocolo en profundidad
  40. 37. Forzar HTTP/1.1 para comparar
  41. 38. Solicitar HTTP/2 cuando esté admitido
  42. 39. Inspeccionar la versión HTTP negociada
  43. 40. Inspeccionar la IP remota
  44. 41. Sobrescribir el DNS para una sola solicitud
  45. 42. No edites /etc/hosts solo para probar un endpoint
  46. 43. Establecer el encabezado Host con cuidado
  47. 44. Usar un proxy de forma explícita
  48. 45. Omitir el proxy para hosts concretos
  49. 46. Mostrar los encabezados de la solicitud con -v, pero sin exponer tokens
  50. 47. Enviar cookies
  51. 48. Guardar las cookies de la respuesta
  52. 49. Enviar más tarde las cookies guardadas
  53. 50. Enviar un User-Agent personalizado
  54. 51. Añadir un ID de correlación
  55. 52. Inspeccionar los encabezados de límite de tasa
  56. 53. Respetar Retry-After
  57. 54. Enviar solicitudes GET condicionales con ETag
  58. 55. Enviar solicitudes condicionales por fecha de modificación
  59. 56. Descargar y reanudar un archivo grande
  60. 57. Limitar la velocidad de descarga para pruebas controladas
  61. 58. Indicar compatibilidad con respuestas comprimidas
  62. 59. Inspeccionar el tipo de contenido
  63. 60. Detectar páginas de error HTML de proxies o gateways
  64. 61. Escribir el cuerpo y el estado por separado en un script de shell
  65. 62. Comprobar el código de salida del proceso de cURL
  66. 63. Un HTTP 500 puede producir el código de salida 0 de cURL sin --fail
  67. 64. Usar HEAD solo para metadatos cuando el servidor lo admita
  68. 65. Probar manualmente una solicitud preflight de CORS
  69. 66. Probar directamente un endpoint OPTIONS
  70. 67. Enviar JSON con PATCH
  71. 68. Enviar DELETE
  72. 69. Evitar poner secretos directamente en la línea de comandos
  73. 70. Usar un archivo de configuración para solicitudes repetibles
  74. 71. Usar .netrc solo cuando su modelo de seguridad encaje
  75. 72. Probar la verificación TLS de forma normal
  76. 73. Evitar -k / --insecure como solución habitual
  77. 74. Usar un certificado de CA personalizado cuando corresponda
  78. 75. Usar un certificado de cliente cuando se requiera mTLS
  79. 76. Depurar el nombre de host/TLS por separado del comportamiento HTTP
  80. 77. Comparar el comportamiento de la API con y sin redirecciones
  81. 78. Ten cuidado al enviar credenciales a través de redirecciones
  82. 79. Comprobar el tamaño del cuerpo de la respuesta
  83. 80. Imprimir una línea de diagnóstico compacta
  84. Qué significa el resultado
  85. Qué revisar
  86. 401 Unauthorized
  87. 403 Forbidden
  88. 404 Not Found
  89. 429 Too Many Requests
  90. 5xx
  91. Tiempo de DNS elevado
  92. Conexión rápida pero TTFB alto
  93. Fallo de TLS
  94. Notas de producción
  95. cURL es una herramienta de reproducción excelente
  96. Protege los secretos
  97. Los reintentos deben respetar la idempotencia
  98. --insecure cambia el modelo de seguridad
  99. El diagnóstico de rendimiento necesita varios tiempos
  100. La sintaxis del shell difiere entre entornos
  101. Las llamadas de producción que cambian el estado requieren una intención explícita
  102. Errores comunes
  103. 1. Confundir Accept y Content-Type
  104. 2. Evaluar el éxito HTTP solo con el código de salida de cURL
  105. 3. Usar -k para «arreglar» TLS
  106. 4. Imprimir tokens en logs verbosos
  107. 5. Reintentar solicitudes POST a ciegas
  108. 6. Construir cadenas de consulta a mano sin codificarlas
  109. 7. Usar --data para payloads binarios
  110. 8. Suponer que HEAD se comporta exactamente igual que GET
  111. 9. Ignorar las redirecciones
  112. 10. Tomar una sola muestra de tiempo como prueba de rendimiento
  113. Siguiente paso
  114. Para profundizar

Problema

Necesitas llamar o diagnosticar rápidamente una API HTTP desde una terminal.

Las tareas de ingeniería típicas incluyen:

  • enviar solicitudes GET, POST, PUT, PATCH o DELETE
  • añadir encabezados y autenticación
  • enviar JSON de forma segura
  • subir o descargar archivos
  • inspeccionar los encabezados de la respuesta y los códigos de estado
  • seguir redirecciones
  • diagnosticar problemas de TLS, DNS, tiempo de espera, proxy o conectividad
  • probar reintentos sin duplicar por accidente solicitudes no seguras
  • reproducir un problema de la API fuera de la aplicación

El objetivo es que la solicitud sea explícita, observable y lo bastante segura como para usarla durante un diagnóstico real en producción.

Respuesta rápida

Solicitud básica a una API JSON:

curl \
  --request GET \
  --url "https://api.example.com/v1/reports/123" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $API_TOKEN"

POST con JSON:

curl \
  --request POST \
  --url "https://api.example.com/v1/reports" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "reportType": "sales",
    "startDate": "2026-10-01",
    "endDate": "2026-10-31"
  }'

Para el diagnóstico, empieza con:

curl \
  --silent \
  --show-error \
  --location \
  --dump-header headers.txt \
  --output body.json \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

Código / comandos

1. Solicitud GET simple

curl "https://api.example.com/v1/status"

Úsala cuando el endpoint no requiera encabezados ni autenticación.


2. Enviar un método HTTP explícito

curl \
  --request PATCH \
  "https://api.example.com/v1/users/123"

Usa --request cuando el método no quede implícito por otra opción.

En muchos casos habituales:

  • --data implica POST, salvo que se especifique otro método
  • --head realiza una solicitud de tipo HEAD
  • --upload-file suele usar la semántica de PUT, salvo que se sobrescriba

Ser explícito mejora la legibilidad de los ejemplos reutilizables.


3. Añadir un encabezado Accept

curl \
  --header "Accept: application/json" \
  "https://api.example.com/v1/users/123"

Accept indica al servidor qué formato de respuesta prefiere el cliente.


4. Enviar JSON

curl \
  --request POST \
  --url "https://api.example.com/v1/users" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Javi",
    "active": true
  }'

Content-Type describe el cuerpo de la solicitud.

No lo confundas con Accept.


5. Usar --json para solicitudes JSON

En versiones modernas de cURL:

curl \
  --json '{
    "name": "Javi",
    "active": true
  }' \
  "https://api.example.com/v1/users"

--json es un atajo que envía JSON y establece los encabezados JSON correspondientes.

Si das soporte a entornos más antiguos, usa en su lugar Content-Type explícito + --data.


6. Enviar JSON desde un archivo

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://api.example.com/v1/reports"

Es más seguro y más fácil de mantener para cuerpos de solicitud grandes.


7. Enviar los bytes sin procesar del cuerpo de la solicitud desde un archivo

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @payload.json \
  "https://api.example.com/v1/reports"

Usa --data-binary cuando el payload deba enviarse sin el procesamiento de tipo formulario que aplica cURL.


8. Añadir un token Bearer

curl \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/profile"

Prefiere las variables de entorno antes que poner secretos directamente en el historial del shell.


9. Autenticación Basic

curl \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.example.com/v1/admin"

No incluyas credenciales en el código de scripts que se suben al control de versiones.


10. Clave de API en un encabezado

curl \
  --header "X-API-Key: $API_KEY" \
  "https://api.example.com/v1/data"

El nombre del encabezado varía según la API.

Usa el esquema de autenticación documentado por el proveedor.


11. Clave de API en la cadena de consulta

curl \
  "https://api.example.com/v1/data?api_key=$API_KEY"

Evita este patrón salvo que sea obligatorio.

Los secretos en la cadena de consulta pueden filtrarse a:

  • los logs
  • el historial del navegador
  • los proxies
  • los sistemas de monitoreo

Los encabezados suelen ser más seguros para las credenciales.


12. Añadir varios encabezados

curl \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Correlation-ID: test-123" \
  "https://api.example.com/v1/orders"

Los ID de correlación son útiles para relacionar la solicitud del cliente con los logs del servidor.


13. Enviar parámetros de consulta de forma segura

curl \
  --get \
  --url "https://api.example.com/v1/reports" \
  --data-urlencode "merchant=ACME & Sons" \
  --data-urlencode "startDate=2026-10-01"

--data-urlencode evita errores de codificación manual.


14. Enviar datos de formulario codificados como URL

curl \
  --request POST \
  --data-urlencode "username=javi" \
  --data-urlencode "scope=reports read" \
  "https://auth.example.com/token"

Esto envía:

application/x-www-form-urlencoded

lo cual es habitual en flujos de OAuth/obtención de tokens.


15. Enviar datos de formulario multipart

curl \
  --form "description=monthly report" \
  --form "file=@report.csv" \
  "https://api.example.com/v1/uploads"

Usa --form para subidas multipart.


16. Subir un archivo directamente

curl \
  --upload-file report.csv \
  "https://storage.example.com/files/report.csv"

Úsalo cuando el endpoint espere que el cuerpo de la solicitud sea el propio archivo.

Comprueba el método y el modelo de autenticación que espera la API.


17. Descargar un archivo con un nombre concreto

curl \
  --output report.csv \
  "https://api.example.com/v1/reports/123/download"

18. Conservar el nombre de archivo proporcionado por el servidor

curl \
  --remote-name \
  "https://example.com/files/report.csv"

Úsalo solo cuando confíes en el origen y en el directorio de destino.


19. Seguir redirecciones

curl \
  --location \
  "https://example.com/download"

Sin --location, cURL normalmente informa de la respuesta de redirección en lugar de seguirla.


20. Mostrar los encabezados y el cuerpo de la respuesta

curl \
  --include \
  "https://api.example.com/v1/status"

--include coloca los encabezados de la respuesta antes del cuerpo en el mismo flujo de salida.

Útil de forma interactiva, menos práctico para la automatización.


21. Guardar los encabezados de la respuesta por separado

curl \
  --dump-header headers.txt \
  --output body.json \
  "https://api.example.com/v1/status"

Úsalo cuando necesites inspeccionar los encabezados y el cuerpo por separado.


22. Mostrar solo los encabezados de la respuesta

curl \
  --head \
  "https://example.com/resource"

Esto solicita una petición HEAD.

Ten en cuenta que no todas las APIs implementan HEAD de forma útil.


23. Imprimir solo el código de estado HTTP

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

En Windows PowerShell, /dev/null no existe de forma nativa. Usa un destino nulo adecuado para el entorno o guarda la respuesta en un archivo.


24. Imprimir el estado y los tiempos

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "status=%{http_code} total=%{time_total}s connect=%{time_connect}s ttfb=%{time_starttransfer}s\n" \
  "https://api.example.com/health"

Útil para separar:

  • el tiempo de conexión
  • el retraso del servidor/TTFB
  • el tiempo total de transferencia

No trates una sola muestra como un benchmark de rendimiento.


25. Imprimir los tiempos de DNS y TLS

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  "https://api.example.com/health"

Úsalo para distinguir:

  • el retraso de DNS
  • el retraso de la conexión TCP
  • el retraso del handshake TLS
  • el retraso de la aplicación/del servidor

26. Fallar ante errores HTTP conservando una salida útil

curl \
  --fail-with-body \
  --show-error \
  "https://api.example.com/v1/resource"

--fail-with-body devuelve un código de salida de fallo para las respuestas de error HTTP y conserva el cuerpo de la respuesta.

Suele ser más útil para scripts que --fail a secas.

Comprueba la versión de cURL si la opción no está disponible en entornos más antiguos.


27. Usar una salida apta para scripts

curl \
  --silent \
  --show-error \
  --fail-with-body \
  "https://api.example.com/v1/resource"

Esta combinación significa:

  • --silent: suprime el indicador de progreso
  • --show-error: sigue imprimiendo los errores de cURL
  • --fail-with-body: código distinto de cero ante errores HTTP, conserva el cuerpo

28. Establecer un tiempo de espera de conexión

curl \
  --connect-timeout 5 \
  "https://api.example.com/health"

Limita cuánto tiempo espera cURL para establecer la conexión.


29. Establecer un tiempo de espera global

curl \
  --max-time 30 \
  "https://api.example.com/v1/reports/123"

Limita la duración total de la solicitud.

Usa valores alineados con la latencia real esperada de la API.


30. Reintentar fallos transitorios

curl \
  --retry 3 \
  --retry-delay 2 \
  --retry-max-time 30 \
  "https://api.example.com/health"

Usa los reintentos sobre todo para operaciones que se pueden repetir de forma segura.


31. Ten cuidado al reintentar POST/PATCH/DELETE

Un reintento puede duplicar efectos secundarios si la API no es idempotente.

Para las operaciones de escritura, prefiere:

  • claves de idempotencia admitidas por la API
  • ID de solicitud del lado del servidor
  • contratos de reintento seguros

No reintentes a ciegas las llamadas que cambian el estado.


32. Usar una clave de idempotencia cuando la API la admita

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data @payload.json \
  "https://api.example.com/v1/payments"

El nombre del encabezado y su comportamiento dependen de cada API.

No inventes un mecanismo de idempotencia que el servidor no admita.


33. Ampliar los reintentos solo cuando esté justificado

Las versiones modernas de cURL admiten:

curl \
  --retry 3 \
  --retry-all-errors \
  "https://api.example.com/health"

Esto amplía los tipos de fallo que se reintentan.

Úsalo con precaución, sobre todo en solicitudes que cambian el estado.


34. Inspeccionar el detalle verboso de la solicitud y la respuesta

curl \
  --verbose \
  "https://api.example.com/v1/status"

Útil para:

  • los encabezados de la solicitud
  • los encabezados de la respuesta
  • las redirecciones
  • la negociación TLS
  • el comportamiento del proxy
  • la reutilización de conexiones

Ten cuidado: la salida verbosa puede exponer credenciales.


35. Nunca pegues la salida verbosa en público sin revisarla

Las trazas verbosas pueden incluir:

encabezados Authorization
cookies
claves de API
nombres de host internos
tokens de sesión

Oculta los secretos antes de compartir logs o tickets.


36. Usar la salida de traza para depurar el protocolo en profundidad

curl \
  --trace-ascii trace.txt \
  "https://api.example.com/v1/status"

Úsalo solo cuando sea necesario.

Los archivos de traza pueden contener encabezados y cuerpos sensibles.

Trátalos como secretos hasta haberlos revisado.


37. Forzar HTTP/1.1 para comparar

curl \
  --http1.1 \
  "https://api.example.com/v1/status"

Úsalo al investigar comportamientos específicos de un protocolo.


38. Solicitar HTTP/2 cuando esté admitido

curl \
  --http2 \
  "https://api.example.com/v1/status"

La compatibilidad real depende de cómo se compiló cURL y de lo que negocie el servidor.


39. Inspeccionar la versión HTTP negociada

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_version}\n" \
  "https://api.example.com/v1/status"

Útil al depurar diferencias entre HTTP/1.1 y HTTP/2.


40. Inspeccionar la IP remota

curl \
  --silent \
  --output /dev/null \
  --write-out "%{remote_ip}\n" \
  "https://api.example.com/health"

Útil al diagnosticar DNS, balanceadores de carga o enrutamiento regional.


41. Sobrescribir el DNS para una sola solicitud

curl \
  --resolve api.example.com:443:203.0.113.10 \
  "https://api.example.com/health"

Esto mantiene el nombre de host original para:

  • el SNI de TLS
  • el encabezado Host

mientras se conecta a la IP especificada.

Úsalo solo para un diagnóstico controlado.


42. No edites /etc/hosts solo para probar un endpoint

--resolve suele ser más seguro, porque solo afecta a esa invocación de cURL.


43. Establecer el encabezado Host con cuidado

curl \
  --header "Host: api.example.com" \
  "https://203.0.113.10/health"

Esto no reemplaza por completo el comportamiento de TLS basado en el nombre de host.

Para probar HTTPS contra una IP concreta, --resolve suele ser mejor opción.


44. Usar un proxy de forma explícita

curl \
  --proxy "http://proxy.example.com:8080" \
  "https://api.example.com/health"

Útil para comprobar si los fallos de la aplicación están relacionados con el proxy.


45. Omitir el proxy para hosts concretos

curl \
  --noproxy "api.example.com" \
  "https://api.example.com/health"

Revisa variables de entorno como:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

cuando cURL se comporta de forma distinta según la máquina.


46. Mostrar los encabezados de la solicitud con -v, pero sin exponer tokens

En las llamadas autenticadas, plantéate probar temporalmente contra un endpoint no sensible u ocultar los secretos en los logs.

No envíes tokens reales de producción a sitios públicos para pegar texto.


47. Enviar cookies

curl \
  --cookie "session_id=$SESSION_ID" \
  "https://api.example.com/profile"

Úsalo solo cuando la API utilice deliberadamente autenticación/estado de sesión basados en cookies.


48. Guardar las cookies de la respuesta

curl \
  --cookie-jar cookies.txt \
  "https://api.example.com/login"

49. Enviar más tarde las cookies guardadas

curl \
  --cookie cookies.txt \
  "https://api.example.com/profile"

Protege los archivos de cookies como si fueran credenciales.


50. Enviar un User-Agent personalizado

curl \
  --user-agent "javi-builds-api-test/1.0" \
  "https://api.example.com/health"

Útil cuando los logs del servidor o los límites de tasa distinguen entre clientes.


51. Añadir un ID de correlación

REQUEST_ID="$(uuidgen)"

curl \
  --header "X-Correlation-ID: $REQUEST_ID" \
  "https://api.example.com/v1/reports"

El nombre exacto del encabezado depende de la API.

Usa un identificador de solicitud estable al correlacionar los logs del cliente y del servidor.


52. Inspeccionar los encabezados de límite de tasa

curl \
  --include \
  "https://api.example.com/v1/data"

Busca encabezados específicos de la API, como:

RateLimit-*
X-RateLimit-*
Retry-After

Los nombres de los encabezados varían según la implementación.


53. Respetar Retry-After

Si el servidor devuelve:

429 Too Many Requests

junto con un encabezado Retry-After, sigue esa indicación en lugar de saturar el endpoint.


54. Enviar solicitudes GET condicionales con ETag

Primero inspecciona:

curl \
  --include \
  "https://api.example.com/v1/config"

Si la respuesta incluye:

ETag: "abc123"

entonces:

curl \
  --header 'If-None-Match: "abc123"' \
  "https://api.example.com/v1/config"

Un 304 Not Modified puede evitar descargar contenido que no ha cambiado.


55. Enviar solicitudes condicionales por fecha de modificación

curl \
  --header "If-Modified-Since: Wed, 01 Oct 2026 12:00:00 GMT" \
  "https://api.example.com/v1/config"

Úsalo solo cuando el servidor admita una semántica de última modificación significativa.


56. Descargar y reanudar un archivo grande

curl \
  --continue-at - \
  --output large-file.zip \
  "https://example.com/large-file.zip"

La reanudación depende de que el servidor admita solicitudes de rango (range requests).


57. Limitar la velocidad de descarga para pruebas controladas

curl \
  --limit-rate 1M \
  --output file.bin \
  "https://example.com/file.bin"

Útil para simular clientes con recursos limitados.


58. Indicar compatibilidad con respuestas comprimidas

curl \
  --compressed \
  "https://api.example.com/v1/data"

Esto solicita al servidor las codificaciones comprimidas admitidas y descomprime la respuesta automáticamente.


59. Inspeccionar el tipo de contenido

curl \
  --silent \
  --output /dev/null \
  --write-out "%{content_type}\n" \
  "https://api.example.com/v1/data"

Útil cuando un endpoint devuelve inesperadamente HTML en lugar de JSON.


60. Detectar páginas de error HTML de proxies o gateways

Si tu cliente espera JSON pero recibe un cuerpo HTML, inspecciona:

curl \
  --include \
  "https://api.example.com/v1/data"

Fíjate en:

  • el código de estado
  • Content-Type
  • Server
  • los encabezados del gateway/proxy

Es posible que el fallo esté upstream de la aplicación.


61. Escribir el cuerpo y el estado por separado en un script de shell

status="$(
  curl \
    --silent \
    --show-error \
    --output response.json \
    --write-out "%{http_code}" \
    "https://api.example.com/v1/data"
)"

echo "HTTP $status"

Así se mantienen separados el cuerpo y el estado, legibles por máquina.


62. Comprobar el código de salida del proceso de cURL

curl \
  --fail-with-body \
  --silent \
  --show-error \
  "https://api.example.com/v1/data"

echo $?

En shells POSIX:

0
→ cURL consideró que la solicitud se completó correctamente

distinto de cero
→ fallo de transporte/protocolo o fallo HTTP con --fail*

No confundas el código de salida de cURL con el código de estado HTTP.


63. Un HTTP 500 puede producir el código de salida 0 de cURL sin --fail

De forma predeterminada, cURL puede transferir correctamente una respuesta 500.

Si los scripts deben fallar ante errores HTTP, usa:

--fail-with-body

e inspecciona también el estado HTTP.


64. Usar HEAD solo para metadatos cuando el servidor lo admita

curl --head "https://example.com/file.zip"

Útil para:

  • la longitud del contenido
  • el ETag
  • la fecha de última modificación
  • las redirecciones

Algunas APIs no implementan HEAD de forma coherente.


65. Probar manualmente una solicitud preflight de CORS

curl \
  --request OPTIONS \
  --header "Origin: https://app.example.com" \
  --header "Access-Control-Request-Method: POST" \
  --header "Access-Control-Request-Headers: authorization,content-type" \
  "https://api.example.com/v1/reports"

Inspecciona encabezados de la respuesta como:

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

CORS lo aplican los navegadores, no cURL.


66. Probar directamente un endpoint OPTIONS

curl \
  --request OPTIONS \
  --include \
  "https://api.example.com/v1/reports"

No des por hecho que todas las APIs exponen metadatos útiles sobre los métodos mediante OPTIONS.


67. Enviar JSON con PATCH

curl \
  --request PATCH \
  --header "Content-Type: application/json" \
  --data '{
    "status": "disabled"
  }' \
  "https://api.example.com/v1/users/123"

Ten cuidado con los endpoints de producción que cambian el estado.


68. Enviar DELETE

curl \
  --request DELETE \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/users/123"

DELETE puede ser destructivo.

Prueba fuera de producción o contra un recurso desechable conocido, salvo que el cambio sea explícitamente intencionado.


69. Evitar poner secretos directamente en la línea de comandos

Arriesgado:

curl \
  --header "Authorization: Bearer real-secret-token" \
  ...

Las líneas de comandos pueden quedar guardadas en el historial del shell o ser visibles mediante la inspección de procesos locales.

Prefiere variables de entorno o herramientas seguras de gestión de secretos.


70. Usar un archivo de configuración para solicitudes repetibles

Ejemplo de curl.conf:

silent
show-error
fail-with-body
header = "Accept: application/json"

Después:

curl --config curl.conf "https://api.example.com/v1/data"

No guardes secretos en un archivo de configuración que se suba al repositorio.


71. Usar .netrc solo cuando su modelo de seguridad encaje

cURL puede usar credenciales de .netrc.

Si lo usas:

  • restringe los permisos del archivo
  • no hagas commit de él
  • entiende a qué hosts se aplica

En muchos flujos de trabajo de producción es preferible una gestión de secretos dedicada.


72. Probar la verificación TLS de forma normal

curl "https://api.example.com/health"

No desactives la verificación de certificados de forma predeterminada.


73. Evitar -k / --insecure como solución habitual

curl --insecure "https://api.example.com/health"

Esto desactiva la verificación de certificados TLS.

Úsalo solo para diagnósticos controlados, cuando entiendas el riesgo.

No lo normalices en scripts de producción.


74. Usar un certificado de CA personalizado cuando corresponda

curl \
  --cacert company-root-ca.pem \
  "https://internal-api.example.com/health"

Así se conserva la verificación TLS y se confía en la CA interna prevista.


75. Usar un certificado de cliente cuando se requiera mTLS

curl \
  --cert client-cert.pem \
  --key client-key.pem \
  "https://mtls.example.com/v1/data"

Protege las claves privadas y el material de los certificados.

Los formatos y opciones exactos dependen de tu compilación de cURL y del empaquetado de los certificados.


76. Depurar el nombre de host/TLS por separado del comportamiento HTTP

Progresión útil:

resolución DNS
→ conexión TCP
→ handshake TLS
→ estado HTTP
→ cuerpo de la aplicación

Usa los tiempos, --verbose y --resolve de forma selectiva para aislar la capa que falla.


77. Comparar el comportamiento de la API con y sin redirecciones

Sin seguirlas:

curl \
  --include \
  "https://example.com/api"

Siguiendo las redirecciones:

curl \
  --location \
  --include \
  "https://example.com/api"

Esto puede revelar problemas de autenticación o de enrutamiento ocultos tras una redirección.


78. Ten cuidado al enviar credenciales a través de redirecciones

Cuando las redirecciones cambian de host, entiende cómo se tratan los encabezados de autenticación y las cookies.

No fuerces el reenvío de credenciales a hosts no relacionados.

Revisa primero los destinos de las redirecciones.


79. Comprobar el tamaño del cuerpo de la respuesta

curl \
  --silent \
  --output /dev/null \
  --write-out "%{size_download}\n" \
  "https://api.example.com/v1/report"

Útil cuando una respuesta de la API que antes era pequeña se vuelve inesperadamente grande.


80. Imprimir una línea de diagnóstico compacta

curl \
  --silent \
  --show-error \
  --output response.out \
  --write-out \
  "status=%{http_code} ip=%{remote_ip} dns=%{time_namelookup}s connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s bytes=%{size_download}\n" \
  "https://api.example.com/v1/data"

Es útil en las notas de incidentes porque recoge tanto el contexto de red como el contexto HTTP.

Qué significa el resultado

Señal Qué ayuda a identificar
Estado HTTP Resultado de la aplicación/del gateway
Código de salida de cURL Éxito o fallo del cliente/transporte/protocolo
time_namelookup Tiempo de resolución DNS
time_connect Tiempo hasta establecer la conexión TCP
time_appconnect Tiempo hasta completar el handshake TLS
time_starttransfer Tiempo hasta el primer byte de la respuesta
time_total Duración total de la solicitud
remote_ip IP del servidor/balanceador de carga realmente alcanzada
content_type Representación de la respuesta devuelta
size_download Tamaño del cuerpo de la respuesta
Encabezados de la respuesta Pistas sobre caché, límite de tasa, autenticación, gateway y trazabilidad

Un modelo mental útil es:

código de salida de cURL
→ ¿se completó correctamente la operación del cliente?

estado HTTP
→ ¿qué respondió el servidor HTTP?

cuerpo de la respuesta
→ ¿qué explicó la aplicación/el gateway?

Qué revisar

401 Unauthorized

Comprueba:

  • token ausente/caducado
  • esquema de autenticación incorrecto
  • audiencia/scope incorrectos
  • problemas de reloj en tokens firmados

No regeneres las credenciales de inmediato sin confirmar antes qué credencial envió realmente la solicitud.

403 Forbidden

Puede que la autenticación se haya completado pero la autorización haya fallado.

Comprueba:

  • permisos
  • rol/scope
  • política del recurso
  • restricciones de IP/red

404 Not Found

Comprueba:

  • la ruta de la URL
  • la versión de la API
  • el ID del tenant/recurso
  • el enrutamiento del gateway
  • si el servicio oculta intencionadamente los recursos no autorizados como 404

429 Too Many Requests

Comprueba:

  • Retry-After
  • los encabezados de límite de tasa
  • la concurrencia de solicitudes
  • los bucles de reintento del cliente

No reintentes de forma agresiva.

5xx

Comprueba si la respuesta provino de:

  • la aplicación
  • el gateway de API
  • el proxy inverso
  • el balanceador de carga

Los encabezados y el cuerpo suelen revelar qué capa falló.

Tiempo de DNS elevado

Investiga el resolvedor y la ruta de red.

Conexión rápida pero TTFB alto

Probablemente se trate de un retraso de procesamiento del servidor/la aplicación/el gateway, más que de la configuración inicial de la red.

Fallo de TLS

Comprueba:

  • el nombre de host
  • la cadena de certificados
  • el almacén de confianza
  • los requisitos de certificado de cliente
  • el reloj del sistema

Evita normalizar --insecure.

Notas de producción

cURL es una herramienta de reproducción excelente

Una solicitud cURL mínima puede separar:

un bug de la aplicación cliente
del
comportamiento de la API/la red/el servidor

Captura la solicitud más pequeña que siga reproduciendo el problema.

Protege los secretos

Los comandos, las trazas verbosas, el historial del shell, los logs de CI y los adjuntos de los tickets pueden exponer:

  • tokens Bearer
  • claves de API
  • credenciales de autenticación Basic
  • cookies
  • certificados de cliente

Oculta los secretos antes de compartir.

Los reintentos deben respetar la idempotencia

Un GET suele poder reintentarse de forma segura.

Un POST puede crear estado duplicado, salvo que la API ofrezca explícitamente una semántica de idempotencia.

--insecure cambia el modelo de seguridad

Es una herramienta de diagnóstico, no una solución para producción.

Si se espera una CA privada, configura correctamente la confianza en esa CA.

El diagnóstico de rendimiento necesita varios tiempos

Un time_total lento por sí solo no te dice si el problema está en:

  • el DNS
  • la red
  • TLS
  • el procesamiento del servidor
  • el tamaño de la descarga

Usa los campos de tiempo en conjunto.

La sintaxis del shell difiere entre entornos

La continuación de línea difiere entre:

  • Bash/zsh: \
  • PowerShell: acento grave (backtick) o splatting/arrays
  • Windows cmd.exe: ^

Las opciones de cURL son las mismas, pero las reglas de comillas difieren.

Las llamadas de producción que cambian el estado requieren una intención explícita

Antes de ejecutar POST/PATCH/DELETE contra producción, confirma:

  • el endpoint
  • el ID del recurso
  • el entorno
  • la identidad de autenticación
  • el payload
  • el efecto secundario esperado

Errores comunes

1. Confundir Accept y Content-Type

Accept describe la respuesta deseada.

Content-Type describe el cuerpo de la solicitud.

2. Evaluar el éxito HTTP solo con el código de salida de cURL

Un 500 puede seguir siendo una transferencia correcta, salvo que se use --fail*.

3. Usar -k para «arreglar» TLS

Esto oculta los problemas de certificados en lugar de resolverlos.

4. Imprimir tokens en logs verbosos

Oculta los secretos antes de compartir la salida.

5. Reintentar solicitudes POST a ciegas

Esto puede duplicar efectos secundarios.

6. Construir cadenas de consulta a mano sin codificarlas

Usa --data-urlencode.

7. Usar --data para payloads binarios

Usa --data-binary o --upload-file cuando importen los bytes sin procesar.

8. Suponer que HEAD se comporta exactamente igual que GET

Algunos servicios implementan HEAD de otra forma o no lo implementan.

9. Ignorar las redirecciones

Una redirección puede explicar un comportamiento inesperado de autenticación, del gateway o de enrutamiento.

10. Tomar una sola muestra de tiempo como prueba de rendimiento

Repite pruebas controladas y compáralas con la telemetría del lado del servidor.

Siguiente paso

Usa el fallo observado para elegir la siguiente investigación.

  • 401/403 → inspecciona la autenticación y la autorización.
  • 404 → verifica la ruta, la versión, el identificador del recurso y el enrutamiento del gateway.
  • 429 → inspecciona los encabezados de límite de tasa y el comportamiento de reintentos/concurrencia del cliente.
  • 5xx → determina si el error lo generó la aplicación o el gateway.
  • DNS lento → investiga el resolvedor y la ruta de red.
  • TLS falla → verifica el nombre de host, la cadena de certificados, la confianza y los requisitos de mTLS.
  • TTFB alto → inspecciona la ejecución del lado del servidor y sus dependencias.
  • La descarga es lenta pero el TTFB es normal → inspecciona el tamaño de la respuesta y el rendimiento de la red.
  • La aplicación cliente falla pero cURL funciona → compara encabezados, autenticación, cuerpo, proxy, TLS y comportamiento ante redirecciones.
  • Necesitas depurar la API de forma sistemática → pasa a Diagnosticar solicitudes de API.

← Todas las guías rápidas