Errores de servidor HTTP 5xx: significado, diagnóstico y soluciones

Qué significa este error y cómo reconocerlo

Puedes observar uno o varios de estos síntomas:

• Un sitio web o una API devuelve un estado HTTP del 500 al 599.
• La respuesta es un error de servidor genérico, un error de aplicación o una página personalizada de un reverse proxy, balanceador de carga o CDN.
• Solo falla una ruta, operación o endpoint de API, mientras las demás páginas siguen funcionando.
• Todo el servicio deja de estar disponible o devuelve errores de forma intermitente.
• Las solicitudes se vuelven lentas antes de terminar con un 504 u otra respuesta 5xx relacionada con una gateway.
• La respuesta incluye un ID de solicitud, un identificador upstream o una cabecera de error específica del servidor que puede ayudar a identificar la capa que la generó.

Causas principales, ordenadas por probabilidad

Entre las causas probables, de las más comunes a las menos comunes, se incluyen:

1. Excepciones de la aplicación o fallos al gestionar la solicitud. Los errores de aplicación no controlados, las rutas de entrada no válidas o un cambio de código defectuoso pueden producir una respuesta 500.
2. Cambios recientes de despliegue o configuración. Una versión publicada, un cambio de variable de entorno, una modificación de enrutamiento o un error de configuración del servidor pueden afectar a una ruta o a todo el servicio.
3. Procesos backend que no están saludables. Un proceso de aplicación detenido, que se bloquea, sobrecargado o inaccesible puede hacer que un proxy devuelva 502 o 503.
4. Fallos de dependencias. Los errores de base de datos, los servicios internos no disponibles, los servicios externos lentos o los pools de conexiones agotados pueden manifestarse como varios códigos 5xx distintos.
5. Tiempos de espera entre capas. Una gateway puede devolver 504 cuando un servicio upstream no responde dentro del tiempo de espera configurado; las dependencias lentas pueden ser la causa subyacente.
6. Presión sobre los recursos. Un uso elevado de CPU o memoria, la saturación de workers, el agotamiento del disco o los límites de conexiones pueden dejar un servicio no disponible o hacer que las solicitudes agoten el tiempo de espera.
7. Mantenimiento o protección intencionada. Un servicio puede devolver 503 durante tareas de mantenimiento, al drenar tráfico, aplicar límites de tasa o protegerse contra una sobrecarga.
8. Comportamiento específico de cada capa. El mismo incidente subyacente puede producir códigos distintos según si la respuesta la generó la aplicación, el servidor web, el reverse proxy, el balanceador de carga o el CDN.

Cómo solucionarlo

1. Registra el fallo con precisión

Anota el código de estado exacto, la URL o la operación de API afectada, la hora —incluida la zona horaria—, la frecuencia, el cuerpo de la respuesta y las cabeceras de respuesta relevantes. Conserva cualquier ID de solicitud o de trace. Si solo estás visitando el sitio, envía estos datos al responsable del servicio en lugar de cambiar la configuración del servidor.

2. Identifica la capa que generó la respuesta

Compara la página de error o el cuerpo JSON, las cabeceras, las cookies y los identificadores del servidor con una respuesta correcta conocida. Un cuerpo de error específico del framework puede apuntar a la aplicación; una página personalizada de una gateway o CDN puede significar que la solicitud falló antes de que el origen produjera una respuesta. Comprueba los logs del reverse proxy, el balanceador de carga o el CDN cuando los logs del origen no contengan ninguna solicitud coincidente.

3. Distingue una interrupción general de un fallo específico de una ruta

Prueba un endpoint de health check aprobado y de bajo impacto, así como una ruta conocida que no esté afectada. Si solo falla una ruta, revisa su código de aplicación, el acceso a datos y las dependencias específicas de la solicitud. Si fallan todas las rutas, prioriza el estado de los procesos, el estado del despliegue, el enrutamiento, la capacidad y las dependencias compartidas. No actualices repetidamente un endpoint de producción como sustituto de un health check.

4. Correlaciona los logs con la misma marca de tiempo

Revisa conjuntamente los logs de la aplicación, el servidor web, el proxy/balanceador de carga y las dependencias. Busca primero el ID de solicitud y, después, limita la búsqueda por marca de tiempo y endpoint. Busca stack traces, reinicios de procesos, mensajes de conexión rechazada, códigos de estado upstream, mensajes de timeout, llamadas fallidas a la base de datos y conexiones rechazadas. Sanitiza las credenciales, los tokens y los datos confidenciales de las solicitudes antes de compartir los logs.

5. Comprueba los cambios recientes y el estado del servicio

Revisa los despliegues, los feature flags, los cambios de configuración, las actualizaciones de certificados o enrutamiento, las tareas de mantenimiento y los cambios de dependencias realizados poco antes de que comenzaran los fallos. Confirma que los procesos backend estén en ejecución y superen sus health checks. Si un cambio reciente está claramente correlacionado con el incidente, utiliza el procedimiento de rollback aprobado por el servicio y cuenta con la autorización correspondiente; no reinicies ni reviertas sistemas de producción sin aprobación operativa.

6. Comprueba las dependencias y la presión sobre los recursos

Inspecciona la accesibilidad y latencia de la base de datos, el estado de los servicios internos, las respuestas de las dependencias externas, el uso del pool de conexiones, la profundidad de las colas, la CPU, la memoria, el espacio en disco, la disponibilidad de workers y los límites de conexiones. Una dependencia que simplemente está lenta puede causar un 504 aunque el proceso de la aplicación siga funcionando. Corrige el componente limitado o que falla en lugar de ocultar el síntoma aumentando los tiempos de espera a ciegas.

7. Usa el código de estado para centrar la investigación

• 500 Internal Server Error: Empieza por los logs de la aplicación, los errores del servidor, la ruta que falla y los cambios recientes de código o configuración.
• 502 Bad Gateway: Inspecciona la conexión entre el proxy y el upstream, así como la respuesta del upstream. Comprueba si el backend está caído, cierra conexiones, devuelve datos malformados o se accede a él mediante una ruta incorrecta.
• 503 Service Unavailable: Comprueba el estado de mantenimiento, los health checks o las comprobaciones de readiness, los controles de sobrecarga, la disponibilidad de los procesos y las dependencias compartidas.
• 504 Gateway Timeout: Mide dónde se consume el tiempo. Comprueba la latencia del upstream, las llamadas a la base de datos o a servicios externos, los pools de conexiones y la configuración de los tiempos de espera en cada capa.
• Otros estados 5xx: Usa la definición exacta del estado y el componente que lo emitió; no supongas que todas las respuestas 5xx tienen la misma causa.

8. Aplica la solución autorizada más específica y verifica de forma segura

Corrige el problema identificado de aplicación, configuración, dependencia o capacidad mediante el proceso de control de cambios del entorno. Después, verifica un endpoint de health check sencillo, la operación que fallaba y funciones dependientes representativas. Confirma que las tasas de 5xx y la latencia hayan vuelto a la normalidad sin crear escrituras duplicadas ni carga adicional. Si la solución implica una acción que cambia el estado, como reiniciar un proceso, drenar tráfico o modificar un tiempo de espera, documenta el impacto previsto y obtén autorización previamente.

Prevención y cómo verificar la solución

• Supervisa la tasa de 5xx, la latencia y la disponibilidad por ruta, servicio y capa que genera la respuesta.
• Utiliza comprobaciones de readiness y liveness que reflejen los requisitos reales de las dependencias sin generar una carga excesiva.
• Mantén los ID de solicitud o de trace coherentes entre proxies, aplicaciones y dependencias.
• Configura tiempos de espera y límites de conexiones acotados y revisados en cada límite entre servicios; evita que las llamadas externas lentas consuman todos los workers.
• Configura alertas para la saturación de recursos, los fallos de procesos, la latencia de la base de datos, el agotamiento del pool de conexiones y la presión sobre el disco antes de que se conviertan en fallos generalizados.
• Utiliza despliegues progresivos, cambios de tráfico basados en el estado de salud y un procedimiento de rollback probado.
• Documenta qué códigos 5xx puede emitir cada proxy, aplicación y dependencia para que quienes respondan al incidente no traten 500, 502, 503 y 504 como intercambiables.
• Prueba periódicamente el comportamiento ante dependencias degradadas y sobrecarga en un entorno autorizado.

Preguntas frecuentes