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