Erro 503 no Magento 2: recupere a loja sem esconder a causa

O erro 503 no Magento 2 indica que alguma camada não conseguiu atender à requisição naquele momento. A resposta pode ter sido gerada pelo servidor web, Varnish, balanceador, PHP-FPM ou pela própria aplicação em modo de manutenção. Reiniciar todos os serviços pode devolver a loja ao ar, mas também apaga pistas e facilita a repetição do problema.

Antes de limpar caches ou executar um novo deploy, registre a URL afetada, o horário, o conteúdo da resposta e quais áreas estão indisponíveis. O roteiro abaixo ajuda a encontrar a origem do 503 e escolher uma recuperação proporcional ao defeito.

Erro 503 no Magento 2: descubra qual camada respondeu

Comece verificando se o erro aparece na página inicial, Admin, checkout, API e arquivos estáticos. Quando apenas uma rota falha, a aplicação pode estar disponível e o defeito pode pertencer a um módulo, integração ou pool específico. Se todas as rotas retornam 503, investigue primeiro manutenção, proxy, servidor web e PHP-FPM.

Consulte a resposta sem depender apenas do navegador:

curl -I https://loja.exemplo.com/
curl -sS -D - -o /dev/null https://loja.exemplo.com/checkout/cart/

Observe o código HTTP, o cabeçalho Server, identificadores de cache e possíveis cabeçalhos adicionados pelo proxy ou balanceador. Faça também uma requisição direta ao backend, quando a arquitetura e as regras de acesso permitirem. Se o backend responde normalmente e o domínio público não, concentre o diagnóstico nas camadas anteriores ao Magento.

1. Verifique se a loja ficou em modo de manutenção

Um deploy interrompido pode deixar o modo de manutenção ativo. No diretório do projeto, consulte o estado usando o mesmo usuário responsável pela aplicação:

bin/magento maintenance:status

Se a manutenção não deveria estar ativa, confirme antes se não existe deploy, importação ou intervenção em andamento. Em seguida, desative-a:

bin/magento maintenance:disable

Não remova arquivos manualmente como primeira tentativa. O estado pode ser intencional, e a exclusão sem coordenação pode liberar tráfego enquanto banco, código e arquivos estáticos ainda estão em versões incompatíveis.

2. Preserve os logs antes de reiniciar serviços

Registre alguns minutos antes e depois da ocorrência. Horários correlacionados ajudam a descobrir se o 503 começou com deploy, pico de tráfego, esgotamento de processos, falha de conexão ou indisponibilidade de um serviço.

Dependendo da infraestrutura, verifique:

• var/log/system.log e var/log/exception.log;
• logs do Nginx ou Apache;
• journal do PHP-FPM, Varnish e demais serviços;
• logs de deploy e automação;
• eventos do balanceador, container ou plataforma de hospedagem.

Procure mensagens no mesmo segundo da resposta 503. Termos como upstream timed out, connection refused, no healthy upstream ou falta de processos disponíveis apontam para causas diferentes. Copie os trechos relevantes antes de rotacionar logs ou reiniciar instâncias.

3. Confirme a saúde do servidor web e do PHP-FPM

O servidor web pode estar ativo, mas incapaz de se conectar ao PHP-FPM. Confira o estado das unidades usando os nomes adotados no ambiente:

systemctl status nginx
systemctl status php-fpm
journalctl -u php-fpm --since "15 minutes ago"

O nome da unidade do PHP pode incluir a versão instalada. Verifique também se o socket ou a porta configurada no Nginx corresponde ao destino em que o pool realmente está escutando.

Se todos os workers estão ocupados, não aumente limites imediatamente. Descubra quais requisições permanecem abertas, quanto tempo consomem e se aguardam banco de dados, Redis, busca ou serviços externos. Aumentar a quantidade de processos sem memória disponível pode agravar a indisponibilidade.

4. Avalie disco, memória e processos

Disco cheio pode impedir a criação de sessões, caches, logs e arquivos temporários. Memória esgotada pode encerrar processos ou deixar o backend sem capacidade para responder. Faça uma leitura inicial:

df -h
df -i
free -m
uptime
ps aux --sort=-%mem | head

Confira tanto espaço quanto inodes. Evite apagar diretórios indiscriminadamente: arquivos de log, dumps e artefatos de deploy podem ser necessários para a análise. Se a lentidão precedeu o erro, use o guia sobre como descobrir o gargalo de um Magento 2 lento para separar saturação de infraestrutura de problemas na aplicação.

5. Isole Varnish, proxy e balanceador

O Varnish pode devolver 503 quando não consegue usar um backend saudável ou quando a resposta demora além do limite configurado. Compare a URL pública com uma chamada direta ao servidor de origem. Analise a saúde do backend, os tempos de conexão e os registros gerados no momento do erro.

Não confunda indisponibilidade com conteúdo antigo. Limpar o cache não corrige um backend recusando conexões e ainda aumenta a carga, pois as próximas páginas precisarão ser reconstruídas. Se o problema for atualização incorreta de conteúdo, siga o checklist específico para cache do Varnish no Magento 2.

Em ambientes com vários nós, teste cada origem individualmente. Uma única instância com código incompleto, manutenção ativa ou PHP-FPM indisponível pode produzir um erro intermitente que desaparece a cada nova tentativa.

6. Teste as dependências usadas pelo Magento

Mesmo quando Nginx e PHP-FPM estão ativos, a aplicação pode não completar a inicialização por falha em uma dependência. Verifique conectividade e autenticação do banco de dados, Redis e mecanismo de busca a partir do mesmo host ou container que executa o Magento.

Evite exibir credenciais no terminal compartilhado ou gravá-las no histórico. Prefira ferramentas e arquivos de configuração protegidos. Confirme também resolução DNS, certificados, portas e limites de conexão. Uma dependência acessível de sua estação pode continuar bloqueada para a rede interna da aplicação.

7. Investigue o deploy sem corrigir permissões às cegas

Se o erro começou após uma publicação, compare o código implantado, dependências instaladas, arquivos estáticos e configuração efetiva. Procure falhas nas etapas de instalação do Composer, compilação, atualização do banco e geração de conteúdo estático.

Não use chmod 777 como solução genérica. Descubra qual usuário executa PHP, deploy e comandos do Magento, e ajuste apenas os diretórios necessários conforme o modelo de permissões do projeto. Também confirme se todos os nós receberam o mesmo artefato e a mesma configuração.

Ordem segura para recuperar a loja

1. Registre URL, horário, cabeçalhos e extensão do impacto.
2. Preserve logs e métricas antes de qualquer reinicialização.
3. Confirme o modo de manutenção e o estado do deploy.
4. Teste a origem sem Varnish ou balanceador, quando possível.
5. Verifique servidor web, PHP-FPM, recursos e dependências.
6. Corrija somente a camada identificada.
7. Reinicie um serviço apenas quando houver motivo técnico registrado.
8. Valide a loja antes de encerrar o incidente.

Depois da recuperação, teste página inicial, categoria, produto, busca, login, carrinho, checkout, Admin e APIs relevantes. Faça ao menos uma compra controlada com os principais meios de pagamento e confirme criação do pedido, retorno do gateway, e-mail e integrações posteriores. Para uma mudança que afete pagamentos, o checklist de testes do checkout e Payment Services ajuda a ampliar a homologação.

O que evitar durante o incidente

• limpar todos os caches antes de coletar evidências;
• reiniciar simultaneamente banco, Redis, busca, Varnish e PHP;
• desativar extensões diretamente em produção sem avaliar dependências;
• alterar timeouts para esconder requisições lentas;
• aumentar workers sem verificar memória e banco de dados;
• liberar a loja após testar somente a página inicial.

Perguntas frequentes sobre erro 503 no Magento 2

O erro 503 significa que o Magento foi invadido?

Não. O código 503 informa indisponibilidade temporária, mas não determina a causa. Modo de manutenção, backend sem resposta, falta de recursos ou falha no PHP-FPM são possibilidades comuns. Investigue logs e arquitetura antes de tirar conclusões.

Limpar o cache resolve o erro 503?

Somente quando a causa está relacionada a dados de cache inconsistentes, o que precisa ser demonstrado. Em outros cenários, a limpeza não corrige o serviço indisponível e pode elevar a carga sobre uma infraestrutura já saturada.

Posso desativar o modo de manutenção imediatamente?

Primeiro confirme se existe deploy ou manutenção em andamento. Desativar o modo antes de concluir atualizações pode expor código, banco e arquivos estáticos incompatíveis aos clientes.

Por que o erro 503 aparece apenas algumas vezes?

Intermitência costuma exigir comparação entre nós, pools e rotas. Um backend defeituoso no balanceador, workers esgotados ou uma dependência instável podem fazer algumas requisições funcionarem e outras falharem.

Conclusão

O erro 503 no Magento 2 deve ser tratado como um problema de camadas, não como um simples pedido para limpar cache. Preservar evidências, identificar quem gerou a resposta e corrigir somente o componente afetado reduz o risco de recorrência e acelera uma recuperação confiável.

Se a indisponibilidade continua ou envolve múltiplos serviços, solicite uma análise técnica especializada em Magento antes de aplicar mudanças amplas em produção.