El servidor no puede atender solicitudes ahora mismo.
Cuándo usarlo
Mantenimiento o sobrecarga. Incluye Retry-After si sabes cuándo volverá a funcionar.
Causas habituales y soluciones
El servidor rechaza solicitudes a propósito o temporalmente: modo de mantenimiento, sobrecarga, todos los backends fallando los health checks, o un límite de frecuencia, ya que limit_req de nginx devuelve 503 por defecto. En un balanceador de carga, 503 suele significar que no hay destinos registrados o en buen estado: revisa el estado de los destinos, la ruta y el puerto del health check, y si los nuevos despliegues lo superan. El ingress de Kubernetes muestra lo mismo cuando un Service no tiene endpoints listos.
Para un mantenimiento planificado, devuelve 503 con Retry-After en lugar de 200 con una página de mantenimiento, para que los buscadores mantengan tus páginas indexadas; Google tolera un 503 durante uno o dos días, pero las interrupciones más largas pueden hacer que se eliminen URL del índice. Los clientes deberían reintentar con backoff y respetar Retry-After. Mantén los health checks ligeros, para que una base de datos lenta no saque de la rotación a todas las instancias a la vez.
Error del servidor (5xx)
Los códigos 5xx son errores del servidor: puede que la solicitud sea correcta, pero el servidor o algo detrás de él ha fallado. Conviene configurar alertas para ellos.
Cómo se ve
HTTP/1.1 503 Service UnavailableCómo enviarlo
| Node.js / Express | res.status(503).end() |
|---|---|
| Python / Flask | return '', 503 |
| nginx | return 503; |
Cómo comprobarlo
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/