500 Internal Server Error: causas, registros y en qué se diferencia del 502

Por qué el 500 te dice tan poco

El RFC 9110 define el 500 como una condición inesperada que impidió al servidor cumplir la petición. Eso es deliberadamente amplio. Cualquier cosa que la aplicación no previera, desde una referencia nula hasta una conexión a base de datos fallida o un archivo de configuración que no puede interpretar, termina bajo el mismo número.

La vaguedad también es una medida de seguridad. Una página de 500 nunca debería filtrar trazas de pila, rutas de archivo, fragmentos de SQL o versiones de librerías al público, porque son exactamente los detalles que quiere un atacante. Así que el código se queda genérico en la respuesta, y el detalle va a un registro que solo puedes leer tú. Ese intercambio es correcto, y hace que un solo dato sea más útil que cualquier otro: dónde viven tus registros.

500 frente a 502, 503 y 504

Los cuatro son errores de servidor, pero los producen componentes distintos y señalan problemas distintos. Acertar con esto ahorra la mayor parte del tiempo de depuración.

• 500 viene de la propia aplicación. Algo se ejecutó y lanzó una excepción. El registro de la aplicación tiene una traza de pila.
• 502 viene de un proxy delante de la aplicación, que recibió una respuesta inválida o una conexión cerrada del backend. El backend a menudo no registra nada, porque nunca terminó la petición. Consulta la guía del 502.
• 503 es un rechazo, no una caída. El servidor está sobrecargado o en mantenimiento y está rechazando trabajo a propósito, normalmente con Retry-After.
• 504 es un tiempo de espera agotado. El backend era accesible pero no respondió dentro del límite del proxy. La petición a menudo sigue ejecutándose entre bastidores.

Un atajo directo: 500 significa que tu código se rompió, 502 significa que tu backend está caído o se comporta mal, 503 significa que tu servidor está diciendo que no a propósito, 504 significa que tu backend va demasiado lento. Toda la familia se compara en el resumen de la familia 5xx.

Qué causa un 500

• Excepciones no controladas en el código de la aplicación. La categoría más grande con diferencia. Un valor nulo, una conversión de tipo fallida, un índice de array fuera de rango, una división por cero en una ruta que nadie probó.
• Fallos de base de datos. Pool de conexiones agotado, credenciales rotadas, la base de datos se reinició, una consulta que entra en interbloqueo o agota el tiempo de espera.
• Dependencias que faltan o se rompen tras un despliegue. Un paquete que no se instaló, un archivo que la compilación no copió, una variable de entorno que existe en pruebas y no en producción.
• Errores de sintaxis en la configuración. En Apache, una sola directiva inválida en un archivo .htaccess produce 500 para cada petición bajo ese directorio.
• Permisos y propiedad de archivos. La aplicación no puede leer un archivo de configuración ni escribir en un directorio de caché, sesión o subida.
• Límites de recursos. Un límite de memoria, un límite de tiempo de ejecución o un disco lleno. Suelen producir 500 intermitentes que siguen el ritmo del tráfico.
• Fallos de APIs de terceros que el código llama sin ningún plan de respaldo, así que una caída remota se convierte en tu página de error.

Cómo diagnosticar un 500

1. Confirma el código y quién lo produjo. Una página de error de marca puede esconder el estado real:

   curl -sS -o /dev/null -D - https://example.com/failing-page

   Revisa la línea de estado y cualquier cabecera Server o de CDN. Si el error lo firma una red de borde y el origen responde 200, no estás mirando en absoluto un 500 de tu aplicación.
2. Abre primero el registro de la aplicación. Ahí es donde está la traza de pila. Los registros del framework, el flujo de registro de la plataforma o el stdout del contenedor, el que use tu stack, y hazlos coincidir por marca de tiempo y ruta de la petición.
3. Luego el registro de errores del servidor web. El error_log de Apache, el error.log de nginx, o el Registro de eventos de Windows para IIS. Si la aplicación nunca registró nada, el fallo ocurrió antes de que se ejecutara tu código, lo que señala a la configuración o al entorno de ejecución.
4. Reprodúcelo deliberadamente. Averigua si el 500 afecta a una URL, a un método HTTP, a un usuario o a todo. Un 500 solo en POST normalmente significa el manejo de formularios o una ruta de escritura. Un 500 para un solo usuario normalmente significa sus datos.
5. Activa los errores detallados en un entorno no público. Nunca en producción. Reprodúcelo en pruebas con la salida de error completa, que convierte un 500 genérico en una línea de código concreta.
6. Comprueba qué cambió. El último despliegue, un cambio de configuración, una renovación de certificado, una actualización de dependencias o una migración de base de datos. Si el sitio estaba bien hace una hora, la respuesta casi siempre está en el último cambio.
7. Comprueba los recursos del host. Espacio en disco, memoria y número de conexiones. Un disco que se llenó de registros produce 500 que parecen completamente ajenos al código.

Los 500 que solo devuelve una página

La mayoría de los 500 no tumban todo el sitio. Una ruta, un formulario o una región se rompe mientras la página de inicio sigue cargando, así que nada parece mal desde fuera y los errores salen a la luz días después como registros perdidos. Una comprobación HTTP programada sobre las páginas que importan, no solo la de inicio, compara el código devuelto contra el esperado y avisa en el momento en que una ruta empieza a responder 500. Las alertas pueden llegar por correo, SMS, llamada de voz, Slack, Telegram y más, así que un fallo nocturno llega a quien esté de guardia en lugar de esperar a la mañana. HostTracker monitoriza sitios web desde 2004.