503 Service Unavailable: sobrecarga, manutenção e Retry-After

Vivo, e recusando o trabalho

Para devolver um 503, alguma coisa precisa estar rodando: ela aceitou a conexão TCP, interpretou a requisição e gerou uma resposta. Só esse fato já elimina uma classe inteira de problemas. O host está no ar, o caminho de rede funciona, o TLS foi terminado e o servidor web ou proxy está funcionando. O que falta é capacidade ou disposição.

A RFC 9110 acrescenta uma ressalva: um servidor não é obrigado a usar 503 quando está sobrecarregado. Alguns simplesmente recusam a conexão. O 503 é, portanto, a forma educada da sobrecarga. Se você recebe uma conexão recusada ou um tempo esgotado em vez de um 503, está diante de uma falha diferente e normalmente pior.

Dois vizinhos são fáceis de confundir. Um 504 Gateway Timeout significa que o backend foi acionado e nunca respondeu a tempo; a requisição chegou a ser tentada. Um 503 significa que a requisição foi recusada antes de o trabalho de verdade começar. A família inteira é comparada na visão geral dos 5xx.

Retry-After, e por que você deveria sempre enviá-lo

A RFC 9110 permite que um 503 carregue um cabeçalho Retry-After, em uma de duas formas: um número de segundos a esperar, ou uma data HTTP absoluta.

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

Não custa nada. Clientes e bibliotecas bem-comportados recuam pelo intervalo indicado em vez de martelar um servidor que já está sofrendo. Rastreadores de buscadores tratam a URL como temporariamente indisponível e voltam depois, em vez de interpretar a queda como remoção de conteúdo. O seu próprio monitoramento e as suas ferramentas de status ganham um tempo de recuperação esperado explícito para exibir.

Um 503 não é cacheável por padrão, então intermediários não vão continuar servindo essa resposta depois que o serviço se recuperar.

O que causa um 503

• Sobrecarga. Todas as threads, processos ou slots de conexão estão ocupados, então novas requisições são rejeitadas em vez de ficarem na fila indefinidamente. Costuma começar de forma intermitente no pico e virar constante conforme a carga cresce.
• Modo de manutenção. Um interruptor intencional, vindo de um sinalizador do framework, de um arquivo de manutenção ou de uma regra do proxy. Aqui o 503 está fazendo exatamente o que deve.
• Uma dependência está fora do ar. Uma aplicação bem escrita que não consegue alcançar o banco de dados, o cache ou a fila deveria devolver 503 em vez de um stack trace, porque a condição é temporária e não é culpa da requisição.
• Nenhum backend saudável. Um balanceador de carga com todos os membros reprovando na verificação de saúde não tem para onde rotear, e muitos devolvem 503 nesse estado.
• Implantações e reinícios. A janela entre drenar o processo antigo e o novo ficar pronto.
• Descarte deliberado de carga. Circuit breakers e controle de admissão devolvem 503 de propósito para proteger as partes do sistema que ainda funcionam.
• Esgotamento de recursos no host. Memória, descritores de arquivo ou espaço em disco no fim, o que impede que novo trabalho comece.

O padrão do 503 durante a implantação

Esse é o 503 mais comum que não é um incidente de verdade, e ele tem um formato reconhecível: uma rajada curta de 503, de alguns segundos a poucos minutos, começando exatamente em um lançamento e terminando sozinha. Cruze os horários com o seu histórico de implantações antes de investigar qualquer outra coisa.

Bem executado, um 503 de manutenção deve:

1. Devolver o código de status verdadeiro. Uma página de manutenção servida com 200 diz aos rastreadores que o seu conteúdo agora é um aviso de manutenção, o pior desfecho possível para uma janela planejada.
2. Incluir Retry-After com uma estimativa realista da janela.
3. Ser estática e barata. A página de manutenção não deve depender do banco de dados nem da aplicação que você acabou de tirar do ar.
4. Liberar os seus próprios endereços para que a equipe possa conferir o novo lançamento antes de reabrir.
5. Estar agendada no monitoramento como janela de manutenção, para que uma parada planejada não acione quem está de plantão.

A correção para os 503 não planejados de implantação é uma atualização gradual controlada por saúde: suba o processo novo, espere ele passar em uma verificação de prontidão, e só então drene e pare o antigo. Feito direito, não existe janela em que ninguém possa atender.

Como corrigir um 503 não planejado

1. Confirme o código e leia os cabeçalhos, incluindo se um Retry-After foi enviado e qual componente assinou a resposta:

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

2. Descarte o modo de manutenção primeiro. Procure um sinalizador ou arquivo de manutenção deixado no lugar depois de um lançamento. Acontece mais do que qualquer um admite.
3. Verifique a saúde do backend. Em um balanceador de carga, veja quantos membros estão passando nas verificações. Zero membros saudáveis já é a resposta.
4. Olhe a saturação. Uso dos pools de workers e conexões, memória, conexões de banco de dados e profundidade das filas. Um 503 sob carga com tudo no teto é capacidade, não bug.
5. Verifique as dependências. Se o banco de dados, o cache ou uma API crítica está fora do ar, resolva isso em vez da camada web.
6. Alivie a carga e depois ache a causa. Escalar horizontalmente ou aumentar limites restabelece o serviço, mas um 503 que apareceu sem aumento de tráfego normalmente esconde uma consulta lenta ou um vazamento que vai voltar.

503 no horário de pico e janelas de manutenção agendadas

Os 503 de sobrecarga costumam ser intermitentes muito antes de virarem constantes, aparecendo nos horários de pico e passando sozinhos. Essa fase inicial é fácil de perder num navegador e óbvia em um registro contínuo. Uma verificação HTTP programada que exige o código de status esperado transforma essas falhas dispersas em uma tendência visível, com horários anexados, para você agir antes de a fase intermitente virar uma queda. Agendar janelas de manutenção na mesma ferramenta impede que 503 planejados gerem alertas.