503 Service Unavailable

O que este erro significa e como reconhecê-lo

• O navegador, cliente de API ou ferramenta de monitoramento informa 503 Service Unavailable ou Service Temporarily Unavailable.
• O erro aparece durante tráfego intenso e desaparece quando a demanda diminui.
• O site permanece indisponível após uma atualização ou deployment do CMS porque o modo de manutenção não foi desativado.
• O erro continua enquanto um banco de dados, serviço de cache ou API upstream necessária está indisponível.
• Apenas determinadas URLs, clientes, padrões de solicitação ou backends recebem respostas 503 devido a rate limiting, uma regra de WAF, roteamento ou um health check não saudável do load balancer.
• Os cabeçalhos da resposta ou uma página de erro gerada pelo proxy indicam que a solicitação pode não ter chegado à aplicação.

Causas principais, por probabilidade

1. Sobrecarga do servidor — CPU, memória, conexões ativas, workers do servidor web, workers do PHP-FPM ou conexões do banco de dados estão esgotados pela demanda normal ou por um pico de tráfego.
2. Modo de manutenção travado — Uma atualização ou deployment do CMS ativa um sinalizador de manutenção, mas não o remove após uma interrupção. No WordPress, isso pode ser um arquivo .maintenance órfão.
3. Dependência necessária indisponível — A aplicação não consegue acessar um banco de dados, camada de cache ou API interna necessária para atender à solicitação. A dependência pode estar em execução, mas inacessível a partir do host ou da rede da aplicação.
4. Rate limiting ou comportamento intencional do WAF — Um rate limiter ou firewall de aplicação web pode retornar respostas 503 quando o tráfego excede um limite ou corresponde a uma regra de segurança.
5. Health check incorreto do load balancer — Um check pode marcar instâncias de backend saudáveis como indisponíveis porque usa o caminho errado ou espera o código de resposta incorreto.
6. Problema de configuração do proxy ou upstream — Um reverse proxy, CDN ou serviço upstream pode gerar o 503 antes que a aplicação receba a solicitação.

Como corrigir

1. Identifique qual camada gerou o 503

Verifique os cabeçalhos da resposta e compare os logs da aplicação, do servidor web, do reverse proxy, da CDN ou WAF e do load balancer. Determine se a resposta veio da aplicação ou foi gerada antes que a solicitação chegasse a ela. Isso evita alterar as configurações da aplicação quando a camada bloqueadora está em outro local.

2. Verifique o uso de recursos no momento da falha

Analise CPU, memória, conexões ativas, workers do servidor web, workers do PHP-FPM, quando aplicável, e conexões do banco de dados. Use ferramentas de monitoramento somente leitura, como top ou htop, painéis de hospedagem e monitoramento de infraestrutura para determinar se um limite foi atingido.

• Se um recurso estiver próximo da capacidade, trate o incidente como um problema de sobrecarga ou capacidade.
• Se o uso de recursos estiver normal, investigue o estado de manutenção, as dependências, os limites de taxa, as regras de WAF e os health checks.

3. Limpe um estado de manutenção incompleto

No WordPress, confirme que a atualização foi concluída ou que o site está autorizado a permanecer em manutenção. Em seguida, conecte-se por SFTP e verifique se há um arquivo chamado .maintenance na raiz do site. Se a atualização foi concluída, mas o arquivo continua presente, remova-o e teste o site novamente. Remover o arquivo altera o estado de manutenção do site; portanto, não faça isso durante uma atualização ou deployment ativo.

Outras plataformas e ferramentas de deployment podem usar um arquivo de sinalização ou uma variável de ambiente. Verifique o processo de atualização ou deployment para identificar o que ativa o modo de manutenção e se a etapa de limpeza foi executada após um processo interrompido.

4. Teste as dependências a partir do servidor da aplicação

Confirme que o banco de dados, a camada de cache, como Redis ou Memcached, e os serviços internos necessários estão em execução e acessíveis a partir do servidor da aplicação. Verifique erros de conexão, falhas de autenticação, timeouts e entradas nos logs dos serviços.

Uma dependência pode estar operacional em geral, mas inacessível a partir do host específico da aplicação devido a acesso à rede, credenciais, roteamento ou uma falha no nível do serviço.

5. Resolva a sobrecarga real

Identifique o recurso limitante antes de aumentar qualquer configuração. O gargalo pode estar na CPU, memória, conexões do banco de dados, conexões do servidor web ou workers do PHP-FPM.

Para obter alívio de curto prazo, reduza o trabalho caro, aumente um limite somente quando o host tiver capacidade ociosa suficiente e a alteração estiver autorizada, ou adicione cache para páginas adequadas. Para uma demanda recorrente, considere uma CDN ou camada de cache e capacidade adicional de backend, em vez de aumentar os limites repetidamente.

6. Verifique limites de taxa, regras de WAF e health checks do load balancer

Analise os logs do Nginx, Apache, CDN ou de outros proxies e sistemas de segurança em busca de regras que retornem respostas 503 intencionalmente. Inspecione os caminhos dos health checks, os códigos de status esperados e o registro dos backends. Se apenas determinadas URLs, clientes ou backends falharem, essa evidência pode diferenciar controle de tráfego ou roteamento de uma indisponibilidade completa do site.

7. Verifique o reparo

Repita a solicitação que falhou e verifique os logs da aplicação, do proxy e das dependências. Confirme que as solicitações normais funcionam e, quando possível, teste com um nível de tráfego ou horário semelhante. Certifique-se de que a correção resolve a condição que desencadeou o erro, em vez de apenas eliminar um sintoma temporário.

Prevenção e como verificar a correção

• Garanta que os scripts de deployment e atualização removam os sinalizadores de manutenção em uma etapa de limpeza ou finally, inclusive após falhas parciais.
• Monitore CPU, memória, conexões ativas, uso de workers e conexões do banco de dados, com alertas antes do esgotamento da capacidade.
• Armazene em cache páginas e operações de banco de dados adequadas para que picos de tráfego consumam menos capacidade de backend.
• Teste os health checks do load balancer usando o caminho correto e o código de resposta esperado.
• Revise as alterações de rate limiting e WAF para que respostas 503 intencionais possam ser diferenciadas de falhas do serviço.
• Mantenha disponíveis os logs da aplicação, do proxy, das dependências e da infraestrutura para o mesmo intervalo de tempo, permitindo correlacionar as falhas.
• Após uma correção, verifique o site em condições semelhantes às que acionaram o erro original.

Perguntas frequentes