O servidor não consegue atender requisições no momento.
Quando usar
Manutenção ou sobrecarga. Inclua Retry-After se você souber quando volta.
Causas comuns e soluções
O servidor está recusando requisições de propósito ou temporariamente: modo de manutenção, sobrecarga, todos os backends falhando nos health checks, ou um limite de taxa, já que o limit_req do nginx retorna 503 por padrão. Em um load balancer, 503 geralmente significa que não há targets registrados ou saudáveis: verifique a saúde dos targets, o caminho e a porta do health check, e se os novos deploys passam nele. O ingress do Kubernetes mostra o mesmo quando um Service não tem endpoints prontos.
Para manutenção planejada, retorne 503 com Retry-After em vez de 200 com uma página de manutenção, para que os mecanismos de busca mantenham suas páginas indexadas; o Google tolera 503 por um ou dois dias, mas indisponibilidades mais longas podem derrubar URLs. Os clientes devem tentar de novo com backoff e respeitar o Retry-After. Mantenha os health checks leves, para que um banco de dados lento não tire todas as instâncias de rotação ao mesmo tempo.
Erro do servidor (5xx)
Os códigos 5xx são erros do servidor: a requisição pode estar certa, mas o servidor ou algo por trás dele falhou. Vale a pena configurar alertas para eles.
Como fica
HTTP/1.1 503 Service UnavailableComo enviar
| Node.js / Express | res.status(503).end() |
|---|---|
| Python / Flask | return '', 503 |
| nginx | return 503; |
Como verificar
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/