503 Service Unavailable: sobrecarga, mantenimiento y Retry-After

Vivo, y rechazando el trabajo

Para devolver un 503 hace falta que algo esté funcionando: aceptó la conexión TCP, analizó la petición y generó una respuesta. Ese solo hecho descarta toda una clase de problemas. La máquina está en marcha, el camino de red funciona, TLS terminó y el servidor web o el proxy operan. Lo que falta es capacidad o voluntad.

El RFC 9110 añade un matiz: un servidor no está obligado a usar el 503 cuando se sobrecarga. Algunos simplemente rechazan la conexión. Un 503 es, por tanto, la forma educada de la sobrecarga. Si recibes una conexión rechazada o un tiempo agotado en lugar de un 503, estás ante un fallo distinto y por lo general peor.

Dos vecinos se confunden con facilidad. Un 504 Gateway Timeout significa que el backend aceptó la petición y luego nunca respondió a tiempo; el intento se hizo. Un 503 significa que la petición se rechazó antes de empezar el trabajo real. La familia entera se compara en el resumen de los 5xx.

Retry-After, y por qué conviene enviarlo siempre

El RFC 9110 permite que un 503 lleve una cabecera Retry-After, en cualquiera de dos formas: un número de segundos de espera o una fecha HTTP absoluta.

HTTP/1.1 503 Service Unavailable
Retry-After: 300
Content-Type: text/html

No cuesta nada. Los clientes y las bibliotecas que se portan bien esperan el intervalo indicado en lugar de machacar un servidor que ya va justo. Los rastreadores de los buscadores tratan la URL como temporalmente no disponible y vuelven más tarde en vez de interpretar la caída como una retirada de contenido. Tus propias herramientas de monitoreo y de estado reciben un tiempo de recuperación previsto que mostrar.

Un 503 no es almacenable en caché por defecto, así que los intermediarios no lo seguirán sirviendo después de que el servicio se recupere.

Qué provoca un 503

• Sobrecarga. Todos los hilos, procesos o huecos de conexión están ocupados, así que las peticiones nuevas se rechazan en lugar de encolarse indefinidamente. Suele empezar de forma intermitente en las horas punta y volverse constante a medida que crece la carga.
• Modo mantenimiento. Un interruptor intencionado, desde un indicador del framework, un archivo de mantenimiento o una regla del proxy. Aquí el 503 hace exactamente lo que debe.
• Una dependencia está caída. Una aplicación bien escrita que no puede llegar a su base de datos, su caché o su cola debería devolver un 503 y no una traza de error, porque la condición es temporal y la petición no tiene la culpa.
• Ningún backend sano. Un balanceador de carga con todos sus miembros suspendiendo la comprobación de salud no tiene a dónde enrutar, y muchos devuelven 503 en ese estado.
• Despliegues y reinicios. La ventana entre vaciar el proceso antiguo y que el nuevo esté listo.
• Descarte deliberado. Los cortacircuitos y el control de admisión devuelven 503 a propósito para proteger las partes del sistema que aún funcionan.
• Agotamiento de recursos en la máquina. Sin memoria, sin descriptores de archivo o con el disco lleno, lo que impide arrancar trabajo nuevo.

El patrón del 503 durante un despliegue

Es el 503 más habitual que no es un incidente de verdad, y tiene una forma reconocible: una ráfaga corta de 503, de unos segundos a un par de minutos, que empieza justo en una publicación y termina sola. Contrasta las marcas de tiempo con tu historial de despliegues antes de investigar otra cosa.

Bien hecho, un 503 de mantenimiento debería:

1. Devolver el código de estado real. Una página de mantenimiento servida con un 200 les dice a los rastreadores que tu contenido ahora es un aviso de mantenimiento, que es el peor resultado posible para una ventana planificada.
2. Incluir Retry-After con una estimación realista de la ventana.
3. Ser estática y barata. La página de mantenimiento no debería depender de la base de datos ni de la aplicación que acabas de apagar.
4. Dejar pasar tus propias direcciones para que el equipo pueda verificar la nueva versión antes de reabrir.
5. Estar programada en el monitoreo como ventana de mantenimiento, para que una caída planificada no despierte a quien esté de guardia.

La solución para los 503 no planificados de despliegue es una actualización progresiva controlada por salud: arranca el proceso nuevo, espera a que supere una comprobación de disponibilidad y luego vacía y detén el antiguo. Bien hecho, no hay ninguna ventana en la que nadie pueda servir.

Cómo solucionar un 503 no planificado

1. Confirma el código y lee las cabeceras, incluido si se envió un Retry-After y qué componente firmó la respuesta:

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

2. Descarta primero el modo mantenimiento. Busca un indicador o un archivo de mantenimiento que se quedó puesto tras una publicación. Pasa más a menudo de lo que nadie admite.
3. Comprueba la salud del backend. En un balanceador de carga, mira cuántos miembros están superando las comprobaciones. Cero miembros sanos es una respuesta inmediata.
4. Fíjate en la saturación. Uso de procesos y del pool de conexiones, memoria, conexiones a base de datos y profundidad de cola. Un 503 bajo carga con todo en su techo es capacidad, no un fallo de código.
5. Revisa las dependencias. Si la base de datos, la caché o una API crítica están caídas, arregla eso y no la capa web.
6. Alivia la carga y luego busca la causa. Escalar o subir límites restablece el servicio, pero un 503 que apareció sin subida de tráfico suele esconder una consulta lenta o una fuga que volverá.

Los 503 de hora punta y las ventanas de mantenimiento programadas

Los 503 por sobrecarga suelen ser intermitentes mucho antes de volverse constantes: aparecen en las horas punta y se van solos. Esa fase temprana es fácil de pasar por alto desde un navegador y evidente en un registro continuo. Una verificación HTTP programada que compruebe el código de estado esperado convierte esos fallos dispersos en una tendencia visible con sus horas, así que puedes actuar antes de que la fase intermitente se convierta en una caída. Programar las ventanas de mantenimiento en la misma herramienta evita que los 503 planificados generen alertas.