Códigos 5xx explicados: cuando el problema es tu servidor
Un código de estado 5xx significa que falló tu infraestructura, no la petición del visitante. El servidor aceptó la petición, la entendió, y luego no pudo producir una respuesta válida, así que cada 5xx de tu sitio es una incidencia que te pertenece.
Qué separa el 5xx del 4xx
El RFC 9110 define el 5xx como "Server Error": el servidor es consciente de que ha cometido un error o es incapaz de realizar el método solicitado. Esa es toda la distinción. Un 404 dice "aquí no hay nada". Un 500 dice "aquí hay algo y me he roto al producirlo".
De ahí se siguen dos consecuencias. Primero, un 5xx normalmente se puede reintentar, porque la misma petición bien podría tener éxito un segundo después en cuanto se recupere el componente que falla. Segundo, los buscadores tratan un 5xx como una señal temporal y ralentizan el rastreo en lugar de desindexar de inmediato, aunque un 5xx persistente durante días acaba costando páginas indexadas.
Qué salto falló
Lee un código 5xx como un mapa de dónde murió la petición. Casi todo sitio moderno pone al menos un proxy delante de la aplicación, así que el código te dice qué lado de ese límite falló.
| Código | Quién lo produjo | Qué pasó |
|---|---|---|
| 500 Internal Server Error | La propia aplicación | Excepción no controlada o condición inesperada dentro de la app |
| 501 Not Implemented | El servidor | El método de la petición no se admite en absoluto |
| 502 Bad Gateway | El proxy, la CDN o el balanceador de carga | El backend respondió, pero con algo inválido, o cerró la conexión |
| 503 Service Unavailable | El servidor o el proxy, deliberadamente | Sobrecargado o en mantenimiento, y rechazando trabajo a propósito |
| 504 Gateway Timeout | El proxy, la CDN o el balanceador de carga | El backend nunca respondió a tiempo |
| 505 HTTP Version Not Supported | El servidor | La versión del protocolo de la petición no se admite |
502, 503 y 504 llevan el mayor valor diagnóstico, porque cada uno nombra un fallo distinto del mismo backend: respuesta inválida, respuesta rechazada, ninguna respuesta. La guía del 502 Bad Gateway cubre el primero en profundidad, incluidas las líneas de registro del proxy que identifican el fallo exacto.
Causas habituales detrás de las respuestas 5xx
- Caídas de la aplicación. Una excepción no controlada, una conexión a base de datos fallida o un valor nulo en un sitio inesperado produce 500 en cualquier ruta que toque la parte de código rota.
- El proceso del backend no se está ejecutando. Un servidor de aplicación detenido, un pool de PHP-FPM muerto o un contenedor que falló su comprobación de salud no le da al proxy con quién hablar, lo que se manifiesta como 502.
- Agotamiento de recursos. Sin memoria, sin descriptores de archivo, sin hilos de trabajo o sin conexiones de base de datos. Normalmente empieza como errores intermitentes bajo carga antes de volverse constante.
- Dependencias lentas. Una consulta lenta, una API de terceros lenta o un arranque en frío empuja el tiempo de respuesta más allá del tiempo de espera del proxy y se convierte en 504.
- Despliegues y reinicios. Cualquier ventana en la que el proceso antiguo ya se ha detenido y el nuevo todavía no ha empezado a servir produce una racha de 502 o 503.
- Errores de configuración. Una dirección de upstream equivocada, una configuración TLS mala entre el proxy y el backend, o un desajuste de protocolo como hablar HTTP a un puerto HTTPS.
- Disco lleno. Una causa infravalorada. Los registros o los archivos temporales llenan el volumen, las sesiones o las cachés dejan de escribir, y la aplicación empieza a fallar de formas que parecen aleatorias.
Cómo abordar un 5xx
- Confirma el código y su origen. Obtén las cabeceras directamente y mira qué componente firmó la respuesta:
Una cabeceracurl -sS -o /dev/null -D - https://example.com/Server:o de CDN en el error te dice si lo generó el borde o el origen. - Prueba el origen directamente, saltándote el proxy. Si el backend responde 200 en su propio puerto mientras la URL pública responde 502, el fallo está en la capa del proxy o en el enlace entre los dos.
- Lee el registro de errores del proxy a continuación, no el de la aplicación. Los proxies inversos nombran el fallo con precisión, por ejemplo
connect() failed (111: Connection refused)oupstream timed out, lo que separa de inmediato "backend caído" de "backend lento". - Luego lee el registro de la aplicación. Para un 500, la traza de pila es la respuesta. Para el 502 y el 504 la aplicación a menudo no registra nada en absoluto, y esa ausencia ya es informativa por sí misma.
- Comprueba los recursos del host. Memoria, disco, número de conexiones y saturación de workers. Un 5xx intermitente bajo tráfico casi siempre es un límite que se está alcanzando.
- Mira qué cambió. Los despliegues, los cambios de configuración, las renovaciones de certificado y las actualizaciones de dependencias explican una gran parte de los inicios repentinos de 5xx.
Detectar errores 5xx intermitentes
Los errores 5xx son a menudo intermitentes, que es lo que los hace difíciles de detectar a mano: la página que recargas funciona, y la que cargó tu cliente no lo hizo. Una comprobación HTTP programada se ejecuta de forma continua y muestrea el sitio mucho más a menudo de lo que tú puedes, así que una racha de errores se vuelve visible como un patrón en lugar de como quejas dispersas. Comprobar desde muchas ubicaciones también separa un fallo real de servidor de un problema de enrutamiento o de borde que afecta solo a una parte del mundo, por lo que la monitorización de disponibilidad distribuida usa puntos de control repartidos entre regiones en lugar de un único punto de vista. Si el código que falla resulta ser 403, 404 o 429 en su lugar, la petición nunca llegó a un backend roto, y la guía de la familia 4xx es el punto de partida correcto.