503 Service Unavailable

Qué significa este error y cómo reconocerlo

• El navegador, cliente de API o herramienta de monitorización informa de 503 Service Unavailable o Service Temporarily Unavailable.
• El error aparece durante periodos de tráfico intenso y desaparece cuando disminuye la demanda.
• El sitio sigue sin estar disponible después de una actualización o despliegue del CMS porque no se desactivó el modo de mantenimiento.
• El error continúa mientras una base de datos, servicio de caché o API upstream necesarios no están disponibles.
• Solo determinadas URL, clientes, patrones de solicitud o backends reciben respuestas 503 debido a un límite de velocidad, una regla del WAF, el enrutamiento o una comprobación de estado no saludable del balanceador de carga.
• Las cabeceras de respuesta o una página de error generada por el proxy indican que la solicitud quizá no llegó a la aplicación.

Causas principales, ordenadas por probabilidad

1. Sobrecarga del servidor — La CPU, la memoria, las conexiones activas, los workers del servidor web, los workers de PHP-FPM o las conexiones a la base de datos se agotan debido a la demanda normal o a un pico de tráfico.
2. Modo de mantenimiento atascado — Una actualización o despliegue del CMS activa un indicador de mantenimiento, pero no lo elimina después de una interrupción. En WordPress, puede tratarse de un archivo .maintenance huérfano.
3. Dependencia necesaria no disponible — La aplicación no puede acceder a una base de datos, capa de caché o API interna necesaria para atender la solicitud. La dependencia puede estar funcionando, pero ser inaccesible desde el host o la red de la aplicación.
4. Limitación de velocidad o comportamiento intencionado del WAF — Un limitador de velocidad o firewall de aplicaciones web puede devolver respuestas 503 cuando el tráfico supera un umbral o coincide con una regla de seguridad.
5. Comprobación de estado incorrecta del balanceador de carga — Una comprobación puede marcar como no disponibles instancias backend saludables porque utiliza la ruta equivocada o espera un código de respuesta incorrecto.
6. Problema de configuración del proxy o del upstream — Un reverse proxy, CDN o servicio upstream puede generar el 503 antes de que la aplicación reciba la solicitud.

Cómo solucionarlo

1. Identifica qué capa generó el 503

Comprueba las cabeceras de respuesta y compara los logs de la aplicación, el servidor web, el reverse proxy, la CDN o el WAF, y el balanceador de carga. Determina si la respuesta procedía de la aplicación o se generó antes de que la solicitud llegara a ella. Esto evita cambiar la configuración de la aplicación cuando la capa que bloquea la solicitud está en otro lugar.

2. Comprueba el uso de recursos en el momento del fallo

Revisa la CPU, la memoria, las conexiones activas, los workers del servidor web, los workers de PHP-FPM si corresponde y las conexiones a la base de datos. Utiliza herramientas de monitorización de solo lectura como top o htop, paneles de hosting y monitorización de infraestructura para determinar si se alcanzó algún límite.

• Si un recurso estaba cerca de su capacidad, trata el incidente como un problema de sobrecarga o capacidad.
• Si el uso de recursos era normal, investiga el estado de mantenimiento, las dependencias, los límites de velocidad, las reglas del WAF y las comprobaciones de estado.

3. Borra un estado de mantenimiento incompleto

En WordPress, confirma que la actualización ha terminado o que el sitio está autorizado para realizar tareas de mantenimiento. Después, conecta mediante SFTP y comprueba si existe un archivo llamado .maintenance en la raíz del sitio. Si la actualización terminó pero el archivo permanece, elimínalo y vuelve a probar el sitio. Eliminar el archivo cambia el estado de mantenimiento del sitio, así que no lo hagas durante una actualización o despliegue activo.

Otras plataformas y herramientas de despliegue pueden utilizar un archivo indicador o una variable de entorno. Revisa el proceso de actualización o despliegue para identificar qué activa el modo de mantenimiento y si su paso de limpieza se ejecutó después de una interrupción.

4. Prueba las dependencias desde el servidor de la aplicación

Confirma que la base de datos, la capa de caché, como Redis o Memcached, y los servicios internos necesarios están activos y son accesibles desde el servidor de la aplicación. Comprueba si existen errores de conexión, fallos de autenticación, timeouts y entradas relevantes en los logs del servicio.

Una dependencia puede estar operativa en general, pero ser inaccesible desde un host de aplicación concreto debido al acceso de red, las credenciales, el enrutamiento o un fallo a nivel del servicio.

5. Resuelve la sobrecarga real

Identifica el recurso limitante antes de aumentar cualquier configuración. El cuello de botella puede estar en la CPU, la memoria, las conexiones a la base de datos, las conexiones del servidor web o los workers de PHP-FPM.

Para obtener un alivio a corto plazo, reduce el trabajo costoso, aumenta un límite solo cuando el host tenga suficiente capacidad disponible y el cambio esté autorizado, o añade caché para las páginas adecuadas. Si la demanda es recurrente, considera una CDN o una capa de caché y capacidad backend adicional en lugar de aumentar los límites repetidamente.

6. Comprueba los límites de velocidad, las reglas del WAF y las comprobaciones de estado del balanceador de carga

Revisa los logs de Nginx, Apache, la CDN u otros proxies y sistemas de seguridad para detectar reglas que devuelvan respuestas 503 intencionadamente. Inspecciona las rutas de las comprobaciones de estado, los códigos de estado esperados y el registro de los backends. Si solo fallan determinadas URL, clientes o backends, esta evidencia puede distinguir un problema de control del tráfico o enrutamiento de una interrupción de todo el sitio.

7. Verifica la reparación

Repite la solicitud que falló y comprueba los logs de la aplicación, el proxy y las dependencias. Confirma que las solicitudes normales funcionan y, cuando sea posible, realiza la prueba con un nivel de tráfico o una hora del día similares. Asegúrate de que la solución aborda la condición que activó el fallo y no solo elimina un síntoma temporal.

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

• Asegúrate de que los scripts de despliegue y actualización eliminen los indicadores de mantenimiento en un paso de limpieza o finally, incluso después de fallos parciales.
• Monitoriza la CPU, la memoria, las conexiones activas, el uso de workers y las conexiones a la base de datos, con alertas antes de agotar la capacidad.
• Usa caché para las páginas y operaciones de base de datos adecuadas, de modo que los picos de tráfico consuman menos capacidad del backend.
• Prueba las comprobaciones de estado del balanceador de carga con la ruta correcta y el código de respuesta esperado.
• Revisa los cambios en los límites de velocidad y el WAF para poder distinguir las respuestas 503 intencionadas de los fallos del servicio.
• Mantén disponibles los logs de la aplicación, el proxy, las dependencias y la infraestructura para el mismo intervalo de tiempo, de modo que los fallos puedan correlacionarse.
• Después de aplicar una solución, verifica el sitio en condiciones similares a las que activaron el error original.

Preguntas frecuentes