Explorar guías rápidas · APIs

Tecnología: APIsCategoría: Solución de problemasNivel: IntermedioActualizado

Diagnosticar solicitudes de API

Diagnostica solicitudes de API que fallan o son lentas aislando DNS, TLS, autenticación, enrutamiento, límites de tasa, payloads, gateways, errores de la aplicación, reintentos y dependencias downstream.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Reproducir fuera de la aplicación
  5. 2. Capturar por separado el estado, el cuerpo y los encabezados
  6. 3. Añadir un ID de correlación
  7. 4. Probar el método HTTP exacto
  8. 5. Enviar el cuerpo de solicitud exacto
  9. 6. Confirmar el Content-Type de la solicitud
  10. 7. Confirmar Accept por separado
  11. 8. Diagnosticar el tiempo de DNS
  12. 9. Ver a qué IP se llegó
  13. 10. Forzar la resolución DNS para una prueba controlada
  14. 11. Comprobar el tiempo de conexión TCP
  15. 12. Comprobar el tiempo del handshake TLS
  16. 13. Inspeccionar los detalles de TLS
  17. 14. No usar --insecure como solución
  18. 15. Usar la CA interna correcta
  19. 16. Probar mTLS cuando sea obligatorio
  20. 17. Detectar la influencia de un proxy
  21. 18. Omitir el proxy para un host
  22. 19. Forzar el uso de un proxy para comparar
  23. 20. Comprobar el comportamiento de las redirecciones
  24. 21. No enviar credenciales a ciegas a través de redirecciones
  25. 22. Depurar la autenticación por separado
  26. 23. Distinguir 401 de 403
  27. 24. Verificar la autorización sobre el tenant/recurso
  28. 25. Diagnosticar un 404
  29. 26. Diagnosticar un 405
  30. 27. Diagnosticar un 409
  31. 28. Diagnosticar un 412
  32. 29. Diagnosticar un 415
  33. 30. Diagnosticar un 422
  34. 31. Diagnosticar un 429
  35. 32. Evitar las tormentas de reintentos
  36. 33. Reintentar solo cuando la semántica de la operación lo permita
  37. 34. Usar claves de idempotencia en creaciones reintentables cuando estén admitidas
  38. 35. Diagnosticar un 500
  39. 36. Diagnosticar un 502
  40. 37. Diagnosticar un 503
  41. 38. Diagnosticar un 504
  42. 39. Identificar qué capa devolvió el error
  43. 40. Medir el tiempo hasta el primer byte
  44. 41. Medir el tamaño de la respuesta
  45. 42. Comprobar la compresión
  46. 43. Revisar la paginación antes de culpar a la latencia
  47. 44. Reproducir una página concreta
  48. 45. Mantener filtros idénticos al comparar páginas
  49. 46. Validar la estructura de la respuesta JSON
  50. 47. Inspeccionar los encabezados de la respuesta por separado del análisis JSON
  51. 48. Confirmar la codificación de caracteres si el texto está dañado
  52. 49. Comprobar el tamaño de la solicitud ante un 413
  53. 50. Comprobar el tamaño de los encabezados ante un 431
  54. 51. Probar CORS por separado de la accesibilidad de la API
  55. 52. Si cURL funciona pero el navegador falla
  56. 53. Si funciona en local pero falla en CI
  57. 54. Si funciona en local pero falla en un contenedor
  58. 55. Si falla una sola región
  59. 56. Si falla un solo cliente
  60. 57. Si todos los clientes fallan a la vez
  61. 58. Si los fallos empiezan después de un despliegue
  62. 59. Si los fallos son intermitentes
  63. 60. Detectar patrones de caducidad de tokens
  64. 61. Evitar avalanchas de renovación de tokens
  65. 62. Comprobar la sincronización del reloj
  66. 63. Comprobar el comportamiento de reutilización de conexiones
  67. 64. Probar solicitudes repetidas
  68. 65. Comparar versiones de HTTP cuando sea relevante
  69. 66. Inspeccionar la versión de HTTP negociada
  70. 67. No confundir el tiempo de espera del cliente con el del servidor
  71. 68. Alinear deliberadamente los presupuestos de tiempo de espera
  72. 69. Evitar reintentar más allá del plazo de quien llama
  73. 70. Revisar las dependencias downstream en solicitudes lentas
  74. 71. Medir por separado los tiempos de cada dependencia
  75. 72. Revisar el comportamiento de las consultas a la base de datos
  76. 73. Comprobar el agotamiento del pool de conexiones
  77. 74. Comprobar la saturación de hilos/del bucle de eventos
  78. 75. Comprobar el costo de serialización en respuestas enormes
  79. 76. Revisar las transformaciones del gateway
  80. 77. Revisar el WAF/la política de seguridad
  81. 78. Revisar la caché
  82. 79. Omitir la caché solo si la API admite una vía de diagnóstico segura
  83. 80. Comparar el comportamiento del ETag
  84. 81. Comprobar la idempotencia ante fallos de escritura
  85. 82. Distinguir un fallo de transporte de un fallo HTTP
  86. 83. Comprobar el código de salida de cURL
  87. 84. No ocultar el cuerpo del error en la automatización
  88. 85. Registrar un informe mínimo del incidente
  89. 86. Comparar solicitudes correctas y fallidas
  90. 87. Reproducir con la solicitud más pequeña
  91. 88. Cambiar una sola variable cada vez
  92. 89. No desactivar controles de seguridad para que la prueba pase
  93. 90. Detenerse cuando la evidencia apunta fuera de la API
  94. Qué significa el resultado
  95. Qué revisar
  96. Los fallos se concentran en un cliente
  97. Los fallos se concentran en una IP de backend
  98. Los fallos empiezan cuando caduca el token
  99. El cuerpo de un 5xx es HTML
  100. Los 429 aumentan tras la primera respuesta de limitación
  101. TTFB alto pero CPU de la API sana
  102. API rápida en local, lenta a través del gateway
  103. Tiempo de espera agotado en un POST seguido de registros duplicados
  104. Notas de producción
  105. La calidad de la reproducción importa
  106. Proteger los secretos en los diagnósticos
  107. Los tiempos de espera y los reintentos interactúan
  108. Los gateways cambian la superficie de diagnóstico
  109. El monitoreo debe preservar la correlación
  110. Una solicitud correcta no demuestra que todo esté sano
  111. Errores comunes
  112. 1. Empezar por el código de la aplicación antes de revisar DNS/TLS/estado
  113. 2. Probar una solicitud distinta de la que falla
  114. 3. Tratar 401 y 403 como intercambiables
  115. 4. Aumentar los tiempos de espera antes de encontrar la dependencia lenta
  116. 5. Reintentar automáticamente todos los fallos
  117. 6. Usar --insecure como solución permanente de TLS
  118. 7. Compartir trazas detalladas con secretos
  119. 8. Suponer que todo 5xx viene del código de la aplicación
  120. 9. Mirar solo la latencia media
  121. 10. Cambiar varias cosas a la vez
  122. Siguiente paso
  123. Para profundizar

Problema

Una solicitud de API falla, agota el tiempo de espera, devuelve un estado incorrecto o se comporta de forma distinta según el entorno.

El reto es determinar qué capa está fallando:

cliente
→ DNS
→ red
→ TLS
→ proxy / gateway / balanceador de carga
→ autenticación
→ enrutamiento
→ aplicación
→ base de datos / servicio downstream

El objetivo es reproducir la solicitud fallida más pequeña posible, reunir evidencia suficiente para identificar la capa que falla y evitar cambios al azar que oculten el problema real.

Respuesta rápida

Empieza con una solicitud reproducible:

curl \
  --silent \
  --show-error \
  --location \
  --dump-header headers.txt \
  --output body.json \
  --write-out \
  "status=%{http_code} ip=%{remote_ip} 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/v1/reports"

Después clasifica el fallo:

Sin conexión
→ DNS, enrutamiento, firewall, proxy, puerto

Fallo de TLS
→ nombre de host, cadena de certificados, confianza, mTLS

401
→ autenticación

403
→ autorización / tenant / política

404
→ ruta, versión, recurso, mapeo del gateway

409 / 412
→ conflicto de estado o de concurrencia

415 / 422
→ tipo de contenido o validación

429
→ limitación de tasa / comportamiento de los reintentos

5xx
→ fallo de la aplicación, del gateway o de una dependencia downstream

TTFB lento
→ procesamiento del servidor o de una dependencia

TTFB rápido, total lento
→ tamaño del payload / ruta de transferencia

Registra siempre:

marca de tiempo
ID de solicitud / de correlación
método
URL
estado
encabezados de la respuesta
cuerpo de la respuesta sin datos sensibles
identidad del cliente
tiempos
entorno

Nunca registres credenciales en logs compartidos.

Código / comandos

1. Reproducir fuera de la aplicación

Usa cURL para separar el comportamiento del cliente de la aplicación del comportamiento de la API:

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

Si cURL funciona pero la aplicación falla, compara:

  • URL
  • método
  • encabezados
  • autenticación
  • configuración del proxy
  • confianza TLS
  • tiempo de espera
  • cuerpo de la solicitud
  • manejo de redirecciones

No des por hecho que la culpa es del servidor hasta que ambas solicitudes sean equivalentes.


2. Capturar por separado el estado, el cuerpo y los encabezados

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

Es mejor que mezclarlo todo en la salida del terminal durante el análisis de un incidente.


3. Añadir un ID de correlación

REQUEST_ID="debug-$(date +%s)"

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

Usa el encabezado de correlación documentado por la API si ya existe uno.

El mismo ID debería aparecer en la telemetría del gateway/de la aplicación siempre que sea posible.


4. Probar el método HTTP exacto

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

No pruebes con GET un endpoint POST que falla para concluir que la ruta está sana.

Cada método puede usar un comportamiento distinto de:

  • autorización
  • enrutamiento
  • análisis del cuerpo
  • lógica del backend

5. Enviar el cuerpo de solicitud exacto

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

Usa un payload guardado cuando reproduzcas un problema de producción.

Elimina los campos sensibles antes de compartirlo.


6. Confirmar el Content-Type de la solicitud

Para JSON:

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

Si el servidor devuelve 415, comprueba el encabezado que llega realmente al servicio.

Un proxy o una biblioteca cliente pueden modificarlo.


7. Confirmar Accept por separado

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

Recuerda:

Content-Type
→ formato del cuerpo de la solicitud

Accept
→ formato de respuesta preferido

8. Diagnosticar el tiempo de DNS

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

Si el tiempo de DNS es anormalmente alto respecto a lo habitual en el mismo entorno, revisa:

  • el resolvedor
  • la VPN
  • el DNS corporativo
  • el DNS dividido (split DNS)
  • el DNS del contenedor
  • el DNS de la VNet/VPC

No hagas un diagnóstico a partir de una sola muestra.


9. Ver a qué IP se llegó

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

Útil cuando:

  • el DNS devuelve varias direcciones
  • el tráfico se enruta por región
  • una ruta de balanceador de carga/backend no está sana

10. Forzar la resolución DNS para una prueba controlada

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

Esto conserva el nombre de host para TLS/SNI mientras se conecta a la IP indicada.

Úsalo solo si sabes que la IP de destino es válida.


11. Comprobar el tiempo de conexión TCP

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

Un tiempo de conexión largo puede apuntar a:

  • la ruta de red
  • un firewall
  • un balanceador de carga sobrecargado
  • pérdida de paquetes
  • una ruta de backend inaccesible

12. Comprobar el tiempo del handshake TLS

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

En HTTPS, compara:

time_connect
frente a
time_appconnect

Una diferencia grande puede indicar un retraso en la negociación TLS.


13. Inspeccionar los detalles de TLS

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

Busca:

  • sujeto/SAN del certificado
  • emisor
  • verificación del certificado
  • negociación TLS
  • discrepancia entre SNI y nombre de host
  • requisitos de certificado de cliente

La salida detallada puede exponer encabezados y tokens. Ocúltalos antes de compartirla.


14. No usar --insecure como solución

Ejemplo solo para diagnóstico:

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

Si esto funciona mientras la verificación normal falla, investiga:

  • la cadena de confianza
  • el nombre de host
  • la CA interna
  • la caducidad del certificado
  • el almacén de confianza del sistema

No dejes desactivada la validación de certificados en clientes de producción.


15. Usar la CA interna correcta

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

Esto conserva la verificación TLS.


16. Probar mTLS cuando sea obligatorio

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

Si mTLS falla, revisa ambas cosas:

  • la validación del certificado del servidor
  • la aceptación del certificado del cliente

17. Detectar la influencia de un proxy

Revisa el entorno:

env | grep -i proxy

Variables habituales:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

Una solicitud puede comportarse de forma distinta dentro de:

  • un portátil
  • CI
  • un contenedor
  • una VM
  • un pod de Kubernetes

porque la configuración del proxy es diferente.


18. Omitir el proxy para un host

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

Si la conexión directa funciona pero a través del proxy falla, investiga la política/el enrutamiento del proxy.


19. Forzar el uso de un proxy para comparar

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

Úsalo solo si ese proxy está aprobado para el entorno.


20. Comprobar el comportamiento de las redirecciones

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

Después, síguelas:

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

Las redirecciones pueden ocultar:

  • transiciones de HTTP a HTTPS
  • páginas de inicio de sesión
  • rutas base incorrectas
  • reescrituras del gateway
  • cambios de región

21. No enviar credenciales a ciegas a través de redirecciones

Inspecciona primero el destino de la redirección.

Las credenciales no deben reenviarse a un host ajeno.


22. Depurar la autenticación por separado

Solicitud con token Bearer:

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

Si la respuesta es 401, comprueba:

  • que el token esté presente
  • la caducidad
  • el emisor
  • la audiencia
  • la firma
  • el tipo de token
  • el reloj del cliente

No registres el token en los logs.


23. Distinguir 401 de 403

Interpretación habitual:

401
→ autenticación ausente o no válida

403
→ identidad aceptada pero acción no permitida

Para un 403, revisa:

  • el scope
  • el rol
  • el tenant
  • la propiedad del recurso
  • la política de red/acceso

24. Verificar la autorización sobre el tenant/recurso

En APIs multitenant:

el tenant autenticado
debe coincidir con
el tenant del recurso

Un token válido por sí solo no demuestra el acceso al recurso solicitado.


25. Diagnosticar un 404

Comprueba:

URL base
ruta
método HTTP
versión de la API
ID del recurso
ruta del gateway
mapeo del tenant

Un 404 puede generarlo:

  • el API gateway
  • el enrutador de la aplicación
  • la búsqueda del recurso en la aplicación

Identifica qué capa respondió.


26. Diagnosticar un 405

Si obtienes:

405 Method Not Allowed

inspecciona el encabezado Allow cuando esté presente.

Puede que la ruta exista pero rechace el método.


27. Diagnosticar un 409

Causas típicas:

  • conflicto de concurrencia optimista
  • clave única duplicada
  • transición de estado no válida
  • operación ya completada

No reintentes automáticamente sin entender la semántica del conflicto.


28. Diagnosticar un 412

Un 412 Precondition Failed suele significar que falló una solicitud condicional.

Ejemplo:

If-Match: "old-etag"

El recurso cambió después de que el cliente lo leyera.

Vuelve a cargar el recurso antes de decidir si reintentar.


29. Diagnosticar un 415

Comprueba:

Content-Type
codificación del cuerpo
delimitador multipart (boundary)
serializador del cliente
transformación del gateway

No des por hecho que el cuerpo JSON es válido solo porque el objeto del cliente se serializó localmente.


30. Diagnosticar un 422

Revisa la validación semántica:

  • combinaciones obligatorias
  • relaciones entre fechas
  • reglas de negocio
  • valores de enumeración
  • estado del recurso

La solicitud puede ser sintácticamente válida pero lógicamente inaceptable.


31. Diagnosticar un 429

Inspecciona los encabezados de la respuesta:

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

Busca:

Retry-After
RateLimit-*
X-RateLimit-*

Después revisa:

  • solicitudes por cliente
  • concurrencia
  • reintentos
  • tamaño de lote/página
  • un único cliente que genera demasiado tráfico

32. Evitar las tormentas de reintentos

Patrón incorrecto:

429
→ reintento inmediato
→ 429
→ reintento inmediato

Prefiere un backoff acotado y respeta Retry-After.


33. Reintentar solo cuando la semántica de la operación lo permita

Los estados potencialmente transitorios:

429
502
503
504

pueden ser reintentables.

Pero que sea seguro depende de:

  • la idempotencia
  • el método
  • si el servidor ya pudo haber confirmado el trabajo
  • las recomendaciones del proveedor

No reintentes a ciegas POST/PATCH/DELETE.


34. Usar claves de idempotencia en creaciones reintentables cuando estén admitidas

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

Esto solo funciona si el servidor implementa semántica de idempotencia.


35. Diagnosticar un 500

Un 500 indica un fallo inesperado del lado del servidor.

Registra:

ID de solicitud
marca de tiempo
ruta
metadatos de la solicitud sin datos sensibles
identidad de quien llama

Después correlaciónalo con los logs del servidor.

No expongas stack traces a quien llama.


36. Diagnosticar un 502

Ruta típica:

cliente
→ gateway
→ backend

Un 502 suele significar que el gateway recibió una respuesta upstream no válida o con fallo.

Comprueba:

  • la salud del backend
  • reinicios de conexión
  • el TLS upstream
  • el protocolo de la respuesta
  • los logs del proxy/gateway

37. Diagnosticar un 503

Comprueba:

  • el estado del despliegue
  • el número de backends sanos
  • la sobrecarga
  • el mantenimiento
  • la disponibilidad de las dependencias
  • el descarte de carga (load shedding)

Si Retry-After está presente, respétalo.


38. Diagnosticar un 504

Un 504 suele significar que un gateway/proxy agotó el tiempo de espera aguardando a un servicio upstream.

Comprueba:

tiempo de espera del gateway
duración en la aplicación
duración en la base de datos
duración de la API downstream
tiempo en cola

Aumentar el tiempo de espera no es automáticamente la solución.


39. Identificar qué capa devolvió el error

Inspecciona:

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

Pistas útiles:

Server
Via
X-Request-ID
X-Correlation-ID
encabezados específicos del gateway
Content-Type
formato del cuerpo

Una página de error HTML procedente de una API JSON suele indicar un intermediario.


40. Medir el tiempo hasta el primer byte

curl \
  --silent \
  --output /dev/null \
  --write-out "ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  "https://api.example.com/v1/reports"

Interpretación:

TTFB alto
→ retraso de procesamiento en el servidor/gateway/dependencia

TTFB bajo pero total alto
→ respuesta grande o transferencia lenta

41. Medir el tamaño de la respuesta

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

Los payloads grandes pueden explicar un tiempo total largo incluso cuando la respuesta del servidor empieza rápido.


42. Comprobar la compresión

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

En respuestas JSON grandes, la compresión puede reducir notablemente el tamaño de la transferencia.


43. Revisar la paginación antes de culpar a la latencia

Si el endpoint devuelve un conjunto de datos enorme, comprueba si quien llama:

  • solicita un tamaño de página excesivo
  • recorre offsets profundos
  • recupera campos innecesarios
  • ignora la paginación

El problema puede estar en el uso de la API y no solo en la ejecución del servidor.


44. Reproducir una página concreta

Ejemplo:

curl \
  "https://api.example.com/v1/orders?limit=100&offset=10000"

o:

curl \
  "https://api.example.com/v1/orders?limit=100&after=$CURSOR"

Compara las primeras páginas con las posteriores.

La lentitud con offsets profundos puede deberse a la consulta.


45. Mantener filtros idénticos al comparar páginas

Cambiar los filtros o el orden invalida la comparación.

Usa exactamente los mismos:

  • filtros
  • orden
  • tenant
  • identidad de autenticación

46. Validar la estructura de la respuesta JSON

Con jq:

curl \
  --silent \
  "https://api.example.com/v1/reports" \
  | jq .

Si el análisis falla, inspecciona la respuesta en bruto.

Puede que hayas recibido:

  • HTML
  • un cuerpo vacío
  • JSON truncado
  • un error del proxy

47. Inspeccionar los encabezados de la respuesta por separado del análisis JSON

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

No dejes que un analizador JSON oculte la respuesta HTTP real.


48. Confirmar la codificación de caracteres si el texto está dañado

Inspecciona:

Content-Type: application/json; charset=utf-8

y los bytes reales.

Los problemas de codificación son distintos de los errores de negocio de la API.


49. Comprobar el tamaño de la solicitud ante un 413

Si la respuesta es:

413 Content Too Large

revisa los límites en:

  • la CDN
  • el WAF
  • el balanceador de carga
  • el gateway
  • el servidor web
  • la aplicación

Puede que la aplicación nunca reciba la solicitud.


50. Comprobar el tamaño de los encabezados ante un 431

Causas habituales:

  • cookies demasiado grandes
  • JWT grandes
  • encabezados de trazas repetidos
  • acumulación de encabezados en proxies

De nuevo, un intermediario puede rechazar la solicitud antes de que llegue a la aplicación.


51. Probar CORS por separado de la accesibilidad de la API

Preflight manual:

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

Recuerda:

el navegador bloquea por CORS
!=
la API es inaccesible

cURL no aplica la política CORS del navegador.


52. Si cURL funciona pero el navegador falla

Revisa:

  • los encabezados CORS
  • el preflight
  • las reglas SameSite de las cookies
  • el contenido mixto
  • la política de credenciales del navegador

No depures primero la conexión con el backend si las llamadas directas a la API funcionan.


53. Si funciona en local pero falla en CI

Compara:

DNS
proxy
certificados de CA
disponibilidad de secretos
identidad del servicio
firewall
reglas de salida (egress)
variables de entorno

CI suele tener un entorno de red y de confianza diferente.


54. Si funciona en local pero falla en un contenedor

Comprueba desde dentro del contenedor:

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

Revisa:

  • el DNS
  • el bundle de CA
  • las variables de entorno del proxy
  • el espacio de nombres de red
  • el descubrimiento de servicios
  • los secretos montados

55. Si falla una sola región

Compara:

  • la IP remota
  • la respuesta DNS
  • la región del gateway
  • el pool de backends
  • la versión desplegada
  • la salud de las dependencias regionales

No des por hecho que una API global tiene una única ruta de red idéntica.


56. Si falla un solo cliente

Compara su solicitud exacta con la de un cliente que funcione correctamente.

Busca:

  • un token distinto
  • una URL base incorrecta
  • una versión de API obsoleta
  • un proxy personalizado
  • un tiempo de espera distinto
  • diferencias en el cuerpo de la solicitud

57. Si todos los clientes fallan a la vez

Prioriza los componentes compartidos:

DNS
gateway
proveedor de identidad
despliegue del backend
base de datos
dependencia downstream compartida

Un bug sincronizado en los clientes es menos probable, salvo que haya cambiado un despliegue o una configuración compartidos.


58. Si los fallos empiezan después de un despliegue

Compara:

  • la versión desplegada
  • la configuración de rutas
  • las variables de entorno
  • la configuración de autenticación
  • los cambios de esquema
  • las versiones de las dependencias
  • la política del gateway

Haz rollback solo cuando la evidencia lo respalde.


59. Si los fallos son intermitentes

Registra por cada solicitud:

ID de solicitud
marca de tiempo
IP remota
estado
latencia
instancia del backend
número de reintentos

Los fallos intermitentes suelen estar correlacionados con un único elemento:

  • instancia
  • región
  • dependencia
  • pool de conexiones
  • ciclo de renovación de credenciales

60. Detectar patrones de caducidad de tokens

Si los fallos ocurren a intervalos regulares:

cada 60 minutos
cada 24 horas

revisa:

  • la caducidad del token de acceso
  • la lógica de renovación
  • la invalidación de la caché
  • la rotación de certificados/tokens

61. Evitar avalanchas de renovación de tokens

En clientes con alta concurrencia, varios workers pueden renovar a la vez un token a punto de caducar.

Usa single-flight/bloqueo o una caché de tokens compartida.

Una ráfaga de solicitudes de autenticación puede provocar fallos 401/429 intermitentes.


62. Comprobar la sincronización del reloj

La validación de tokens y TLS puede fallar si la hora del sistema es incorrecta.

Inspecciona el reloj del host/contenedor cuando veas:

  • token aún no válido
  • token caducado de forma inesperada
  • anomalías en la validez de certificados

63. Comprobar el comportamiento de reutilización de conexiones

Un cliente que usa conexiones HTTP en pool puede comportarse de forma distinta a la solicitud puntual de cURL.

Investiga:

  • conexiones obsoletas en el pool
  • cambios de DNS
  • tiempo de espera por inactividad
  • keep-alive del proxy
  • duración de las conexiones en el balanceador de carga

64. Probar solicitudes repetidas

for i in 1 2 3 4 5; do
  curl \
    --silent \
    --output /dev/null \
    --write-out \
    "status=%{http_code} ip=%{remote_ip} total=%{time_total}s\n" \
    "https://api.example.com/health"
done

Esto puede revelar un comportamiento intermitente de un backend/IP.

No conviertas el diagnóstico en producción en una prueba de carga.


65. Comparar versiones de HTTP cuando sea relevante

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

y:

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

Úsalo solo cuando la evidencia apunte a diferencias a nivel de protocolo.


66. Inspeccionar la versión de HTTP negociada

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

67. No confundir el tiempo de espera del cliente con el del servidor

Posibles puntos de fallo:

tiempo de espera del cliente
tiempo de espera del gateway
tiempo de espera de la aplicación
tiempo de espera de la base de datos
tiempo de espera de la API downstream

Determina dónde se genera el agotamiento del tiempo de espera.


68. Alinear deliberadamente los presupuestos de tiempo de espera

Conceptualmente:

tiempo de espera del cliente
>
tiempo de espera del gateway
>
tiempo de espera de las llamadas downstream de la aplicación

puede ser útil para que los fallos downstream afloren antes de que quienes llaman desde fuera se rindan, pero los valores reales dependen de la arquitectura.

No copies valores de tiempo de espera universales.


69. Evitar reintentar más allá del plazo de quien llama

Los reintentos deben caber dentro del presupuesto total de la solicitud.

Un cliente que reintenta tres veces con tiempos de espera largos puede superar con creces la latencia que espera el usuario.


70. Revisar las dependencias downstream en solicitudes lentas

Si el TTFB es alto, revisa:

  • la base de datos
  • la caché
  • el broker de mensajes
  • las APIs downstream
  • las llamadas de identidad
  • el sistema de archivos/almacenamiento de objetos

Puede que el endpoint solo sea la parte visible de una cadena de dependencias más larga.


71. Medir por separado los tiempos de cada dependencia

Una buena telemetría del servidor registra:

duración total de la solicitud
duración en la base de datos
duración de la API downstream
tiempo en cola
duración de la serialización

Sin ese desglose, «la API tardó 8 segundos» no sirve para actuar.


72. Revisar el comportamiento de las consultas a la base de datos

Si la latencia de la API se corresponde con llamadas a la base de datos, revisa:

  • bloqueos
  • consultas de larga duración
  • CPU alta
  • muchas lecturas
  • índices faltantes/ineficientes
  • sensibilidad a parámetros
  • agotamiento del pool de conexiones

No escales a ciegas las instancias de la API para resolver un cuello de botella de la base de datos.


73. Comprobar el agotamiento del pool de conexiones

Los síntomas pueden incluir:

  • agotamientos intermitentes del tiempo de espera
  • más tiempo en cola
  • CPU baja en el backend pese a respuestas lentas
  • fallos con alta concurrencia

Inspecciona las métricas del pool, no solo los logs del endpoint.


74. Comprobar la saturación de hilos/del bucle de eventos

Los síntomas en la aplicación pueden incluir:

  • respuestas lentas pese a dependencias downstream sanas
  • crecimiento de la cola de solicitudes
  • concurrencia en aumento
  • trabajo síncrono bloqueante

Usa telemetría específica del runtime.

No hagas este diagnóstico solo a partir del estado HTTP.


75. Comprobar el costo de serialización en respuestas enormes

Las respuestas JSON grandes y anidadas pueden dedicar un tiempo considerable a:

  • la materialización de objetos
  • la serialización
  • la compresión
  • la transferencia por red

Reduce la estructura del payload antes de limitarte a añadir capacidad de cómputo.


76. Revisar las transformaciones del gateway

Los gateways pueden:

  • reescribir rutas
  • añadir/eliminar encabezados
  • validar tokens
  • limitar la tasa de solicitudes
  • transformar cuerpos
  • almacenar en caché
  • terminar TLS

Compara el comportamiento de solicitudes/respuestas antes y después del gateway cuando la arquitectura lo permita.


77. Revisar el WAF/la política de seguridad

Los 403 inesperados o las solicitudes bloqueadas pueden venir de:

  • una regla del WAF
  • una restricción por IP
  • una restricción geográfica
  • la protección contra bots
  • una política de tamaño de solicitud
  • una regla de patrones sospechosos

Identifica la capa que responde antes de cambiar la autorización de la aplicación.


78. Revisar la caché

Una respuesta obsoleta o incoherente puede venir de:

  • la CDN
  • el proxy inverso
  • el API gateway
  • la caché de la aplicación

Inspecciona:

Cache-Control
Age
ETag
Last-Modified
Via
X-Cache

cuando estén disponibles.


79. Omitir la caché solo si la API admite una vía de diagnóstico segura

No inventes encabezados como:

X-Bypass-Cache: true

salvo que la plataforma los admita explícitamente.

Usa los controles de caché documentados.


80. Comparar el comportamiento del ETag

Solicitud:

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

Después:

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

Útil para depurar clientes que conservan datos obsoletos.


81. Comprobar la idempotencia ante fallos de escritura

Escenario:

el POST agota el tiempo de espera

Estado desconocido:

¿El servidor confirmó la operación antes de que fallara la conexión?

No reintentes a ciegas salvo que el endpoint admita idempotencia o puedas consultar el estado de la operación de forma segura.


82. Distinguir un fallo de transporte de un fallo HTTP

Ejemplos:

fallo de DNS
fallo de TLS
reinicio de la conexión
tiempo de espera agotado antes de la respuesta HTTP

pueden no producir ningún estado HTTP.

Tu cliente debería registrar ambas cosas:

error de transporte
estado HTTP si existe

83. Comprobar el código de salida de cURL

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

echo $?

Un código de salida de cURL distinto de cero no es lo mismo que un código de estado HTTP.


84. No ocultar el cuerpo del error en la automatización

Prefiere:

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

en lugar de --fail a secas cuando el cuerpo contiene diagnósticos útiles.


85. Registrar un informe mínimo del incidente

Plantilla útil:

Marca de tiempo UTC:
Entorno:
Método:
URL/ruta:
Quien llama/cliente:
ID de solicitud:
Estado HTTP:
Error de transporte:
IP remota:
Tiempo de DNS:
Tiempo de conexión:
Tiempo de TLS:
TTFB:
Tiempo total:
Content-Type de la respuesta:
Código/mensaje de error sin datos sensibles:
Reintento realizado:

No incluyas secretos.


86. Comparar solicitudes correctas y fallidas

Haz una comparación lado a lado de:

método
URL
cadena de consulta
encabezados
identidad de autenticación
payload
estado
tiempos
IP remota
entorno

Las diferencias suelen revelar el problema más rápido que leer logs de forma aislada.


87. Reproducir con la solicitud más pequeña

Elimina los elementos opcionales:

  • encabezados
  • parámetros de consulta
  • campos del payload
  • capas envolventes del cliente

hasta que el fallo desaparezca.

Después vuelve a añadirlos de uno en uno.

Así aíslas el desencadenante.


88. Cambiar una sola variable cada vez

Mala forma de diagnosticar:

cambiar el tiempo de espera
cambiar el proxy
cambiar el token
cambiar la ruta
volver a desplegar

todo a la vez.

Pierdes la causalidad.

Prefiere un único cambio controlado con evidencia de antes y después.


89. No desactivar controles de seguridad para que la prueba pase

Evita usar como soluciones permanentes:

--insecure
autenticación desactivada
firewall abierto
WAF desactivado
límite de tasa ilimitado

Si uno de estos cambios aísla la capa que falla, restablece el control y corrige la configuración real.


90. Detenerse cuando la evidencia apunta fuera de la API

Si:

el DNS falla

el siguiente paso no está en el código de la aplicación.

Si:

504 del gateway con una dependencia de base de datos lenta

el siguiente paso no es cambiar el manejador de estados HTTP.

Sigue la evidencia hasta la capa responsable.

Qué significa el resultado

Señal Capa probable
Fallo de DNS / tiempo de DNS alto Configuración de DNS / red
Conexión rechazada Endpoint, puerto, firewall, listener
Fallo de verificación TLS Certificado / confianza / nombre de host
401 Autenticación
403 Autorización, tenant, WAF/política
404 Ruta, versión, recurso, mapeo del gateway
409 / 412 Estado o concurrencia
415 / 422 Formato de la solicitud o validación semántica
429 Limitación de tasa / patrón de solicitudes del cliente
500 Fallo de la aplicación
502 Fallo entre el gateway y el upstream
503 Disponibilidad / sobrecarga / mantenimiento
504 Tiempo de espera agotado en el upstream
TTFB alto Procesamiento en el servidor/gateway/dependencia
Total alto, TTFB bajo Tamaño de la transferencia / rendimiento de la red
cURL funciona, la aplicación falla Diferencia de comportamiento/configuración del cliente
Solo falla una región/instancia Ruta regional/instancia de backend

El mejor modelo de diagnóstico es:

transporte
→ seguridad
→ enrutamiento
→ aplicación
→ dependencias

Qué revisar

Los fallos se concentran en un cliente

Revisa lo específico de ese cliente:

  • credenciales
  • proxy
  • versión del SDK
  • forma de la solicitud
  • bucle de reintentos
  • tenant

Los fallos se concentran en una IP de backend

Sospecha de una instancia no sana o de una ruta regional.

Los fallos empiezan cuando caduca el token

Revisa la renovación y el almacenamiento en caché de los tokens.

El cuerpo de un 5xx es HTML

Probablemente es una respuesta del gateway/proxy/intermediario y no el JSON de la aplicación.

Los 429 aumentan tras la primera respuesta de limitación

Los reintentos de los clientes pueden estar amplificando la carga.

TTFB alto pero CPU de la API sana

Revisa las dependencias downstream, el tiempo en cola, los pools de conexiones y los bloqueos.

API rápida en local, lenta a través del gateway

Revisa la ruta gateway/WAF/proxy y las diferencias de TLS/red.

Tiempo de espera agotado en un POST seguido de registros duplicados

Probablemente el cliente reintentó una operación no idempotente sin un mecanismo de idempotencia seguro.

Notas de producción

La calidad de la reproducción importa

Una buena reproducción incluye los mismos:

  • entorno
  • método
  • encabezados
  • identidad
  • payload
  • ruta

que la solicitud fallida.

Una solicitud simplificada que cambia esas dimensiones puede estar probando otra cosa.

Proteger los secretos en los diagnósticos

Nunca pongas en bruto:

  • tokens de acceso
  • claves de API
  • cookies
  • contraseñas
  • secretos de cliente
  • claves privadas

en tickets o logs compartidos.

Los tiempos de espera y los reintentos interactúan

Un tiempo de espera largo más varios reintentos pueden producir fallos muy largos para el usuario y efectos secundarios duplicados.

Diséñalos en conjunto.

Los gateways cambian la superficie de diagnóstico

En producción, la API visible desde fuera suele incluir varias capas antes de la aplicación.

Captura telemetría en cada frontera relevante.

El monitoreo debe preservar la correlación

Un ID de solicitud que atraviesa:

cliente
→ gateway
→ API
→ servicio downstream

es mucho más útil que líneas de log sin relación entre sí.

Una solicitud correcta no demuestra que todo esté sano

Los problemas intermitentes requieren varias muestras con marca de tiempo y, cuando sea posible, con la identidad del backend/región.

Errores comunes

1. Empezar por el código de la aplicación antes de revisar DNS/TLS/estado

Puedes acabar depurando la capa equivocada.

2. Probar una solicitud distinta de la que falla

Cambiar el método, la autenticación, el payload o el entorno invalida la comparación.

3. Tratar 401 y 403 como intercambiables

Apuntan a áreas distintas.

4. Aumentar los tiempos de espera antes de encontrar la dependencia lenta

Esto puede ocultar el síntoma y empeorar la capacidad.

5. Reintentar automáticamente todos los fallos

Los reintentos pueden duplicar escrituras o crear tormentas de carga.

6. Usar --insecure como solución permanente de TLS

Desactiva la verificación de certificados.

7. Compartir trazas detalladas con secretos

Las trazas de cURL pueden exponer material de autenticación.

8. Suponer que todo 5xx viene del código de la aplicación

Los gateways y los proxies también generan errores.

9. Mirar solo la latencia media

Los fallos intermitentes pueden afectar a una sola región, instancia o dependencia.

10. Cambiar varias cosas a la vez

Pierdes la evidencia necesaria para identificar la causa raíz.

Siguiente paso

Usa la primera capa que falla para decidir qué revisar a continuación.

  • No hay resolución DNS → revisa el resolvedor, la VNet/VPC, el DNS del contenedor, la VPN y el proxy.
  • Fallo de conexión → revisa el endpoint, el puerto, el firewall, el listener y el enrutamiento.
  • Fallo de TLS → revisa el nombre de host, la cadena de certificados, la confianza, mTLS y el reloj del sistema.
  • 401 → revisa la validez del token/clave, el emisor, la audiencia y la caducidad.
  • 403 → revisa el scope, el rol, el tenant, el WAF y la política de IP/seguridad.
  • 404/405 → revisa la ruta, el método, la versión y el mapeo del gateway.
  • 409/412 → revisa las reglas de estado/versión/concurrencia.
  • 415/422 → revisa el Content-Type, el serializador, el payload y la validación de negocio.
  • 429 → revisa los límites de tasa, la concurrencia, los reintentos y la identidad de quien llama.
  • 500 → correlaciona el ID de solicitud con los logs de la aplicación.
  • 502/503/504 → revisa el gateway y las dependencias upstream/del backend.
  • TTFB alto → revisa la ejecución en el servidor y los tiempos downstream.
  • TTFB bajo, total alto → revisa el tamaño del payload, la compresión y la transferencia por red.
  • cURL funciona pero la aplicación falla → compara exactamente los encabezados, el proxy, la autenticación, TLS, las redirecciones y el comportamiento de los tiempos de espera.
  • No aparece nada evidente → compara solicitudes correctas y fallidas, y cambia una sola variable cada vez.

← Todas las guías rápidas