Códigos de Status HTTP

Os códigos de status HTTP 407, 403, 502 e outros erros de proxy indicam problemas específicos encontrados por um cliente ou por um proxy durante o processamento de uma requisição HTTP, geralmente relacionados a autenticação, restrições de acesso ou falhas de conectividade com o servidor upstream.

Um proxy atua como intermediário para requisições de clientes que buscam recursos em outros servidores. Quando um cliente faz uma requisição através de um proxy, o proxy processa essa requisição, podendo modificá-la, antes de encaminhá-la ao servidor de origem. Em seguida, o proxy recebe a resposta do servidor de origem e a repassa ao cliente. Erros podem ocorrer em várias etapas dessa interação, sendo gerados pelo próprio proxy ou repassados de um servidor upstream. Entender esses códigos é essencial para diagnosticar problemas de conectividade de rede e de aplicação.

407 Proxy Authentication Required

O código de status 407 Proxy Authentication Required indica que o cliente precisa se autenticar no proxy antes de prosseguir com a requisição. Esse erro é gerado pelo proxy, não pelo servidor de origem.

Mecanismo

Quando um cliente envia uma requisição para um proxy que exige autenticação e a requisição não contém credenciais de autenticação de proxy válidas (ou não contém credencial alguma), o proxy responde com o status 407. Essa resposta inclui o cabeçalho Proxy-Authenticate, que especifica o(s) esquema(s) de autenticação suportado(s) pelo proxy (por exemplo, Basic, Digest, NTLM).

Ação do cliente

Ao receber uma resposta 407, um cliente em conformidade deve solicitar as credenciais ao usuário ou obtê-las de sua configuração e, então, reenviar a requisição original com o cabeçalho Proxy-Authorization contendo as credenciais apropriadas.

Exemplo

Um cliente tenta acessar http://example.com através de um proxy em proxy.example.com:8080.

Requisição do cliente (inicial):

GET http://example.com/index.html HTTP/1.1
Host: example.com

Resposta do proxy:

HTTP/1.1 407 Proxy Authentication Required
Proxy-Authenticate: Basic realm="Proxy Realm"
Content-Length: 0

Requisição do cliente (após a autenticação):

GET http://example.com/index.html HTTP/1.1
Host: example.com
Proxy-Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Diagnóstico

• Verifique a configuração do cliente: confirme que o cliente (navegador, aplicação, curl) está configurado para usar o proxy correto e possui as credenciais de autenticação necessárias.
• Verifique a configuração do proxy: confirme que as configurações de autenticação do proxy estão como o esperado.
• Validade das credenciais: garanta que o usuário e a senha informados estão corretos para o proxy.
• Regras de firewall/rede: embora seja menos comum no caso do 407, verifique se nenhuma regra de rede está interferindo no handshake de autenticação.

403 Forbidden

O código de status 403 Forbidden indica que o servidor entendeu a requisição, mas se recusa a autorizá-la. Diferente de 401 Unauthorized ou 407 Proxy Authentication Required, a autenticação não fará diferença: o cliente simplesmente não tem permissão para acessar o recurso.

O papel do proxy

Um erro 403 pode ser gerado tanto pelo servidor de origem quanto pelo próprio proxy.

• Gerado pelo servidor de origem: o proxy encaminha a requisição ao servidor de origem, que responde com 403 porque o cliente (ou o proxy em nome do cliente) não tem as permissões necessárias para acessar o recurso solicitado no servidor de origem. O proxy apenas repassa esse código ao cliente.
• Gerado pelo proxy: o proxy pode gerar uma resposta 403 se suas listas internas de controle de acesso (ACLs), políticas ou regras de filtragem de conteúdo proibirem explicitamente que o cliente acesse determinado destino, URL ou tipo de conteúdo. Nesse cenário, a requisição nunca chega ao servidor de origem.

Diferença em relação ao 407

Um erro 407 significa que o proxy exige autenticação para permitir que a requisição prossiga. Um erro 403 significa que o recurso (no proxy ou no servidor de origem) está proibido, independentemente da autenticação (mesmo que a autenticação tenha sido bem-sucedida).

Diagnóstico

• Verifique os logs do proxy: determine se o 403 foi gerado pelo proxy ou repassado de um servidor de origem. Os logs do proxy normalmente mostram se a requisição foi bloqueada internamente.
• Revise as políticas/ACLs do proxy: se o 403 foi gerado pelo proxy, examine sua configuração em busca de filtragem de URL, restrições de domínio, controles de acesso por IP ou políticas de grupos de usuários que possam estar bloqueando a requisição.
• Verifique as permissões no servidor de origem: se o 403 veio do servidor de origem, investigue as permissões de arquivo do servidor de destino, a configuração do servidor web (por exemplo, .htaccess do Apache, diretivas deny do Nginx) ou os controles de acesso no nível da aplicação.
• IP/User Agent do cliente: alguns servidores de origem ou políticas de proxy bloqueiam requisições com base no endereço IP do cliente ou na string de user-agent.

502 Bad Gateway

O código de status 502 Bad Gateway indica que o proxy, atuando como gateway ou proxy, recebeu uma resposta inválida de um servidor upstream que acessou ao tentar atender à requisição.

Mecanismo

Quando um cliente envia uma requisição ao proxy, o proxy a encaminha para um servidor de origem (ou outro proxy). Se o servidor de origem responder com um código de status HTTP ou com dados que o proxy não consiga interpretar como resposta HTTP válida, ou se a conexão com o servidor de origem falhar depois que a requisição foi enviada, o proxy gera um erro 502 e o devolve ao cliente.

Causas comuns

• Servidor upstream fora do ar: o servidor de origem está offline ou inacessível.
• Problemas de conectividade de rede: problemas entre o proxy e o servidor de origem (por exemplo, bloqueio de firewall, problemas de roteamento, falha de resolução DNS).
• Sobrecarga do servidor de origem: o servidor de origem está ocupado demais para responder ou responde com uma mensagem malformada.
• Resposta HTTP inválida: o servidor de origem envia uma resposta que não segue a especificação do protocolo HTTP (por exemplo, cabeçalhos ausentes, dados corrompidos).
• Erros de configuração do proxy: embora seja menos comum no caso do 502, configurações incorretas de servidores upstream no proxy podem contribuir.

Diagnóstico

• Verifique o status do servidor upstream: confirme que o servidor de origem está rodando e acessível diretamente a partir do proxy.
• Verificação do caminho de rede: use ferramentas como ping, traceroute ou telnet a partir do proxy até a porta HTTP do servidor de origem para confirmar a conectividade.
• Logs do proxy: examine os logs de erro do proxy em busca de detalhes sobre a falha de comunicação com o upstream. Esses logs costumam conter mensagens de erro mais específicas sobre a tentativa de conexão com o servidor de origem.
• Logs do servidor de origem: se o servidor de origem estiver ativo, verifique seus logs de acesso e de erro em busca de qualquer indício do motivo pelo qual ele enviou uma resposta inválida ou não respondeu.
• Resolução DNS: garanta que o proxy consegue resolver corretamente o hostname do servidor de origem.

Outros erros comuns de proxy e códigos relacionados

400 Bad Request

Indica que o proxy não conseguiu entender a requisição devido a sintaxe malformada. Esse erro normalmente é gerado pelo próprio proxy quando a requisição HTTP do cliente não segue os padrões do protocolo (por exemplo, cabeçalhos incorretos, codificação de URL inválida).

408 Request Timeout

O cliente não produziu uma requisição dentro do tempo que o proxy estava disposto a esperar. Isso também pode ser gerado pelo proxy se ele não receber uma requisição completa do cliente dentro do período de timeout configurado.

500 Internal Server Error

Uma mensagem de erro genérica, indicando uma condição inesperada encontrada pelo servidor. Se um proxy gera esse código, significa que o próprio proxy encontrou um erro interno que o impediu de atender à requisição. Isso é diferente de erros originados em servidores upstream.

503 Service Unavailable

O proxy está temporariamente incapaz de processar a requisição devido a sobrecarga temporária ou manutenção programada, situação que provavelmente será resolvida após algum tempo. Esse erro é gerado pelo próprio proxy e indica a indisponibilidade dele mesmo.

504 Gateway Timeout

O proxy, atuando como gateway ou proxy, não recebeu uma resposta em tempo hábil de um servidor upstream que precisava acessar para concluir a requisição. Isso difere do 502 porque o 504 implica um timeout (nenhuma resposta dentro de um período definido), enquanto o 502 implica que uma resposta inválida ou corrompida foi recebida.

Comparação dos erros 5xx

Entender as diferenças sutis entre 502 e 504 é fundamental para um diagnóstico eficaz.

Boas práticas no tratamento de erros de proxy

• Logging abrangente: configure os proxies para registrar todos os detalhes de requisição e resposta, incluindo cabeçalhos HTTP completos e timestamps precisos. Esses dados são valiosíssimos para diagnosticar a origem e a natureza dos erros.
• Monitoramento e alertas em tempo real: implemente monitoramento da saúde do proxy, do uso de recursos e de códigos de erro HTTP específicos. Configure alertas para taxas elevadas de erros 4xx e 5xx.
• Páginas de erro detalhadas: personalize as páginas de erro para os códigos gerados pelo proxy (por exemplo, 407, 403 gerado pelo proxy, 5xx) para oferecer mensagens mais informativas aos clientes, incluindo passos de diagnóstico ou informações de contato.
• Health checks de upstream: para proxies que roteiam para vários servidores de origem, implemente health checks ativos para identificar rapidamente serviços upstream com problema e desviar o tráfego deles.
• Orientação aos clientes: forneça documentação clara sobre como configurar aplicações ou navegadores para usar o proxy corretamente, incluindo os detalhes de autenticação.
• Auditoria periódica das políticas: revise regularmente as listas de controle de acesso e as políticas de filtragem do proxy para garantir que estejam alinhadas aos requisitos atuais e não bloqueiem tráfego legítimo por engano.