Error 500, 502, 503: qué significa cada código

Cuando un sitio se rompe, el reflejo es abrir el código. El código de error que aparece en pantalla es una pista más rápida: dice qué capa ha cedido, y los tres más frecuentes señalan tres reparaciones completamente distintas. Cinco minutos de lectura aquí ahorran una hora de búsqueda en el sitio equivocado.

Los tres códigos, en una tabla

El 504 no está en el título y acompaña a los otros tan a menudo que merece su fila: es el único de los cuatro que indica lentitud en lugar de parada.

500: la aplicación se ha caído

El servidor está en pie y ha respondido. Es tu código el que no ha llegado al final.

Las tres causas que más se repiten:

• Un error fatal después de un despliegue: una dependencia que falta, una versión de lenguaje distinta, un archivo de configuración ausente.
• La base de datos ya no responde: servicio parado, conexiones agotadas, contraseña cambiada y no propagada.
• El disco está lleno. Es la causa más subestimada, porque no se parece a nada: las sesiones dejan de escribirse, los registros también, y la aplicación tropieza con errores incoherentes.

Dónde mirar: el registro de la aplicación, en el minuto en que apareció el error. Un 500 casi siempre deja rastro, con un archivo y un número de línea.

502: la máquina de delante ha recibido una mala respuesta

Un 502 viene de un proxy: Nginx, un balanceador, un CDN. Ha transmitido la petición de tu visitante al servidor de detrás y ha recibido de vuelta algo inservible, o nada en absoluto.

Las tres causas habituales:

• El proceso de detrás está muerto o nunca arrancó: PHP-FPM parado, un servicio Node caído, un contenedor que no volvió tras un despliegue.
• La vía de comunicación es falsa: un socket renombrado, un puerto cambiado, una dirección interna que se movió durante una actualización.
• El proceso fue eliminado por falta de memoria. El registro del sistema lo dice, la aplicación no.

Dónde mirar: el estado del servicio situado detrás del proxy, antes que el código. Un 502 es la única de las tres respuestas que casi nunca sale de tu propio programa, y por eso se atribuye mal tan a menudo.

503: el servidor rechaza, temporalmente

Un 503 es una respuesta deliberada: ahora no. O bien el sitio está en modo mantenimiento, o bien el servidor se ha quedado sin capacidad y rechaza en lugar de derrumbarse.

Es la más tranquilizadora de las tres: nada está roto. Es también la que dura más tiempo, porque suele seguir a un pico de tráfico o a una cola que no se vacía. Y es la única que puede ser la respuesta correcta: durante un mantenimiento anunciado, un 503 acompañado de una cabecera Retry-After es exactamente lo que hay que devolver.

Dónde mirar: si ha quedado activa una bandera de mantenimiento, y luego la carga. Un modo mantenimiento olvidado tras un despliegue de viernes es un clásico absoluto. Compruébalo antes de suponer nada sobre la carga: cuesta diez segundos y explica buena parte de los 503.

Dónde leer el registro, según la pila

tail -n 100 /var/log/nginx/error.log        # Nginx, incluidos los 502 y 504
tail -n 100 /var/log/apache2/error.log      # Apache
journalctl -u php8.3-fpm --since "10 min ago"   # PHP-FPM, procesos muertos
tail -n 100 storage/logs/laravel.log        # la aplicación, para los 500
df -h && free -m                            # disco lleno, memoria agotada

El orden importa: el registro del servidor web dice qué capa ha fallado, el registro de la aplicación dice por qué. Empezar por el segundo cuando la avería es un 502 equivale a buscar un error en un archivo que nunca se ejecutó.

Qué comprobar en el alojamiento antes de acusar a tu código

Tres cosas, y llevan dos minutos:

• La página de estado del alojamiento. Un mantenimiento de base de datos compartida produce 500 en todo el mundo a la vez.
• Las cuotas. Número de procesos, memoria por proceso, conexiones simultáneas a la base: superarlas produce exactamente los mismos síntomas que un fallo de programación.
• Un cobro rechazado. Un servicio suspendido por impago responde a menudo con un 503, y el aviso original se fue al spam hace tres semanas.

Recuerda sobre todo que nadie te avisará espontáneamente: una página de estado en verde mientras tu sitio devuelve 500 es una situación perfectamente normal desde el punto de vista del alojamiento, puesto que su máquina responde.

Qué decirle al cliente mientras tanto

Es el párrafo que nadie escribe y que todo el mundo busca. Bastan dos líneas, y no mencionan ningún código:

El sitio muestra un error desde las 14:20. Hemos identificado de dónde viene y estamos trabajando en ello. Le doy noticias a las 15:00.

No digas «error 502», nadie sabe qué es y da la impresión de que recitas. No prometas una hora de restablecimiento mientras la causa sea desconocida. Y avisa antes de que te lo pidan: un cliente que descubre la caída por su cuenta recuerda el incidente, un cliente avisado recuerda la respuesta.

Los tres errores de diagnóstico que más tiempo cuestan

Reiniciar antes de leer. Un reinicio suele borrar el rastro de lo que se rompió: el proceso muerto vuelve, el registro empieza de nuevo, y la avería regresa dos horas después sin que sepas más. Leer primero, reiniciar después, en ese orden, por fuerte que sea la tentación.

Creer que el código señala al culpable. Señala la capa que ha informado del problema, no la que lo ha causado. Un 502 devuelto por Nginx es casi siempre un problema de PHP, y un 500 de la aplicación es a veces un disco lleno, es decir un problema de sistema.

Tratar un incidente aislado como una tendencia. Un único 502 a las tres de la madrugada, durante una rotación de registros, no exige ninguna acción. Tres 502 el mismo día sí. La diferencia solo es visible si algo guarda el historial, que es la aportación real de una vigilancia frente a leer un registro de vez en cuando.

Lo que estos códigos no dicen

No dicen si el visitante ha visto la página. Un usuario cuyo navegador la tenía en caché no ha notado nada; otro, llegado en el mismo momento desde un resultado de búsqueda, ha visto el error a pantalla completa. Tampoco dicen a cuánta gente afecta: un error que solo toca una ruta concreta, un formulario de pedido por ejemplo, puede devolver un volumen ridículo de 500 y costar muy caro.

Lo que los tres tienen en común

En los tres casos, la máquina está en pie. Algo ha respondido. Eso ya descarta el DNS, la red y el alojamiento, y es precisamente lo que hace útil leer este código antes que nada.

Si no responde nada en absoluto, el problema está en otra parte, y los quince primeros minutos transcurren de otro modo.

Dos vecinos merecen distinguirse, porque a menudo se confunden con esta familia. Un 404 no es una avería: es la respuesta correcta a una petición de una página que no existe, y se clasifica con otras reglas. Un aviso de certificado no es un código de error en absoluto: el servidor responde perfectamente, es el navegador el que se niega a mostrar, y esa avería no deja rastro en tus registros.

La pregunta que nadie hace

Sea cual sea el código obtenido, la pregunta útil viene después: ¿cuánto tiempo se estuvo devolviendo antes de que lo supieras? Un 500 que dura cuatro minutos no es un acontecimiento. El mismo 500 descubierto a la mañana siguiente por un cliente es otra historia, y la diferencia no tiene nada que ver con el código.

Es además la única parte que se puede cifrar: lo que cuesta realmente una hora de caída depende mucho menos de la naturaleza de la avería que del tiempo que pasó en pantalla.