Erros de HTTP e do servidor

Sobre esta categoria de erros

# Erros de HTTP e do servidor

Erros de HTTP e do servidor ocorrem quando uma solicitação não pode ser concluída normalmente. Algumas falhas retornam um código de status HTTP, como 500, 502, 503 ou 504. Outras acontecem antes que o navegador receba uma resposta HTTP, gerando mensagens como ERR_CONNECTION_REFUSED ou ERR_CONNECTION_TIMED_OUT.

A mensagem do navegador identifica o sintoma, mas nem sempre o componente que precisa de atenção. Comece localizando o limite em que a falha ocorre: navegador para rede, rede para serviço em escuta, proxy para backend ou aplicação para dependência.

Identifique primeiro o tipo de falha

Um código de status HTTP foi retornado

Um status numérico significa que um componente compatível com HTTP respondeu. Esse componente pode ser o servidor web de origem, um proxy reverso, um balanceador de carga ou uma CDN, e não necessariamente a própria aplicação.

• 500 Internal Server Error: O servidor encontrou uma condição inesperada ao processar a solicitação. Comece pelos logs da aplicação e do servidor web. Consulte o [guia sobre 500 Internal Server Error](/http-500-internal-server-error).
• 502 Bad Gateway: Um proxy recebeu uma resposta inválida, vazia ou inutilizável do backend. Verifique o processo do backend, o host e a porta upstream e a conexão entre o proxy e a origem. Consulte o [guia sobre 502 Bad Gateway](/http-502-bad-gateway).
• 503 Service Unavailable: O serviço não pode atender à solicitação naquele momento. As possíveis causas incluem modo de manutenção, capacidade esgotada, processo indisponível ou falha em uma dependência. Consulte o [guia sobre 503 Service Unavailable](/http-503-service-unavailable).
• 504 Gateway Timeout: Um gateway encaminhou a solicitação, mas não recebeu uma resposta antes de o tempo limite expirar. O backend ainda pode estar em execução, mas lento, sobrecarregado ou aguardando outro serviço. Consulte o [guia sobre 504 Gateway Timeout](/http-504-gateway-timeout).

Um código de status, por si só, não prova qual camada falhou. Analise a identificação da resposta, os cabeçalhos, o horário e os logs para determinar se a resposta veio da origem ou de um intermediário.

O navegador informa uma falha de conexão

Um erro no nível da conexão significa que o navegador não recebeu uma resposta HTTP normal do endpoint esperado.

• ERR_CONNECTION_REFUSED: O destino foi alcançado, mas a conexão foi rejeitada. Verifique se há um serviço escutando na porta esperada e se regras de segurança locais ou da rede afetam o acesso. Para ambientes de desenvolvimento, consulte [ERR_CONNECTION_REFUSED no localhost](/err-connection-refused-localhost).
• ERR_CONNECTION_TIMED_OUT: O navegador aguardou sem receber uma resposta utilizável. Investigue o caminho da rede, o roteamento, a filtragem, o DNS, a acessibilidade do servidor e a disponibilidade de recursos antes de procurar um erro HTTP gerado pela aplicação. Consulte o [guia sobre ERR_CONNECTION_TIMED_OUT](/err-connection-timed-out).

Uma sequência prática de diagnóstico

1. Reproduza e registre a falha

Recarregue uma vez e tente acessar a mesma URL em uma janela privativa ou em outro dispositivo. Registre a URL exata, o texto do erro, o código de status, o horário aproximado e a página de resposta exibida. Uma página personalizada de CDN ou proxy sugere que a solicitação chegou a um intermediário; uma mensagem genérica do navegador pode significar que nenhuma resposta HTTP utilizável chegou.

Se apenas um navegador ou dispositivo falhar, verifique o proxy, a VPN, o cache DNS, as extensões e o software de segurança local. Se a mesma URL falhar em diferentes dispositivos e redes, o servidor, o proxy, a origem ou um caminho de rede compartilhado se tornam causas mais prováveis.

2. Defina o escopo afetado

Determine se o problema afeta uma rota, um host, uma aplicação inteira ou todo o serviço.

• A falha em uma única rota pode indicar um código da aplicação, uma dependência específica da rota ou uma consulta lenta.
• O retorno de 500 em todas as rotas sugere um problema mais amplo na aplicação ou na configuração do servidor.
• Um 502 ou 504 em um proxy direciona a atenção para o processo de origem, a conexão upstream ou a configuração do proxy.
• Uma conexão recusada em uma porta pode significar que o serviço esperado não está escutando, enquanto outros serviços continuam disponíveis.

Compare um endpoint que funciona com o que falha, quando possível. Diferenças no roteamento, na autenticação, nas dependências e no estado do deployment podem ser mais informativas do que alterar configurações não relacionadas do cliente.

3. Verifique o componente que gerou a resposta

Para um 500, correlacione os logs da aplicação e do servidor web com o horário da falha. Para respostas 502, 503 e 504, analise os logs do proxy ou gateway e os logs do backend. Procure por processo parado, deployment com falha, falha de conexão com uma dependência, esgotamento de recursos ou uma solicitação que excede um tempo limite relevante.

Para um ERR_CONNECTION_REFUSED local, verifique se o Apache ou o Nginx está em execução e se a porta configurada está disponível. XAMPP, Laragon e MAMP podem apresentar esse sintoma quando o servidor web não foi iniciado ou quando outro programa impede que ele seja associado à porta esperada.

4. Teste a origem e as dependências separadamente

Quando você administra o serviço, verifique se o backend aceita conexões e responde a um endpoint simples, sem presumir que uma conexão bem-sucedida pelo proxy prove que a aplicação está saudável. Em seguida, verifique os serviços necessários, como o banco de dados ou outras dependências configuradas.

Um backend ativo, mas consistentemente lento, é mais compatível com um 504 do que um backend parado ou que retorna uma resposta inutilizável, o que pode produzir um 502. Um 503 pode ocorrer antes de uma solicitação chegar à aplicação se o serviço estiver deliberadamente indisponível ou se uma dependência necessária não puder ser usada.

Evite recarregar a página repetidamente como método de troubleshooting. Isso pode aumentar a carga enquanto o processo, a dependência ou o problema de timeout subjacente está sendo investigado.

Use os detalhes do erro para localizar a camada

O corpo da resposta, os cabeçalhos e o horário podem revelar qual componente tratou a falha:

• Uma mensagem genérica do navegador geralmente indica que nenhuma resposta HTTP utilizável foi recebida.
• Uma página personalizada de proxy ou CDN indica que um intermediário gerou ou apresentou o erro.
• Uma página de erro específica da aplicação pode apontar mais diretamente para a aplicação de origem.

Para falhas intermitentes, correlacione o horário com deployments, aumentos de tráfego, reinicializações de processos e latência de dependências. Para falhas consistentes, compare uma solicitação que funciona com a solicitação que falha e analise as diferenças de configuração antes de alterar as configurações do servidor.

Para sites que usam Cloudflare, um 504 com a marca Cloudflare geralmente significa que a borda não conseguiu obter uma resposta da origem dentro da janela de timeout aplicável. O [guia sobre 504 Gateway Timeout atrás do Cloudflare](/504-gateway-timeout-cloudflare) explica como separar um problema na origem de um timeout produzido por outro gateway ou pela própria origem.

O que incluir ao pedir ajuda

Um relatório útil inclui:

• O texto exato do erro e o código de status
• O caminho da URL e o horário aproximado da falha
• Se o problema afeta outros usuários, dispositivos ou redes
• Se há um proxy, CDN ou balanceador de carga envolvido
• Entradas relevantes dos logs do servidor web, do proxy e da aplicação, com senhas, tokens e outros segredos removidos

O objetivo é identificar o limite em que a falha ocorre. Depois que esse limite é conhecido, o guia de erro relevante pode fornecer verificações mais específicas, sem tratar causas no navegador, na rede, no proxy e no backend como equivalentes.