Um pequeno conjunto de ferramentas para depurar redirecionamentos e cabeçalhos HTTP em produção

O problema de depurar HTTP em produção

A maioria dos problemas HTTP é invisível no navegador. Uma cadeia de redirecionamento falha silenciosamente, um cabeçalho de cache está errado por um único carácter, uma política CORS bloqueia um pedido sem explicação. As ferramentas de programador do navegador mostram-lhe o resultado da conversa, mas muitas vezes escondem a troca bruta que causou o problema.

Isto é particularmente importante em produção, onde não pode adicionar logging nem reiniciar serviços para ver o que mudou. Precisa de ferramentas que mostrem a conversa HTTP real: cabeçalhos de pedido, cabeçalhos de resposta, códigos de estado, destinos de redirecionamento, tempos. Eis as cinco ferramentas que fazem esse trabalho de forma fiável, além das técnicas no navegador que as complementam.

curl: a base

curl é a primeira ferramenta a usar porque mostra exatamente o que o servidor enviou, sem interpretação do navegador pelo meio.

Para ver cabeçalhos de resposta sem o corpo:

curl -I https://example.com

Para seguir redirecionamentos e ver cada passo:

curl -L -v https://example.com

A flag -v (verbose) mostra o pedido e a resposta completos, incluindo todos os cabeçalhos. A flag -L segue redirecionamentos automaticamente. Em conjunto, mostram toda a cadeia de redirecionamento, que é onde vive a maioria dos problemas em produção.

Para ver apenas os locais de redirecionamento:

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -L https://example.com

Isto é útil quando precisa de verificar uma cadeia de redirecionamento sem o ruído dos cabeçalhos completos. A flag -w formata a saída para mostrar apenas o código de estado e o URL seguinte na cadeia.

curl também permite enviar cabeçalhos personalizados, o que é essencial para testar o comportamento de uma CDN, autenticação ou endpoints de API:

curl -H "Authorization: Bearer token" -H "Accept: application/json" https://api.example.com

httpie: curl com melhores predefinições

httpie é uma ferramenta em Python que faz o que curl faz, mas com uma sintaxe mais fácil de memorizar e uma saída mais fácil de ler. Não é um substituto — curl é mais poderoso e está instalado em mais sistemas —, mas para verificações rápidas, httpie é mais rápido.

Para ver cabeçalhos:

http HEAD https://example.com

Para seguir redirecionamentos:

http --follow --all https://example.com

A flag --all mostra todas as respostas na cadeia de redirecionamento, não apenas a final. É o equivalente a curl -L -v, mas a saída tem cores e é mais fácil de percorrer visualmente.

Para enviar JSON:

http POST https://api.example.com name=value

httpie assume JSON por defeito, o que poupa escrita quando está a testar APIs. Também apresenta a resposta com formatação legível, facilitando a deteção de cabeçalhos malformados ou valores inesperados.

Browser DevTools: aba Network

A aba Network do navegador é por onde deve começar se o problema só acontece no navegador. Mostra-lhe a mesma informação que curl, mas também mostra a interpretação do navegador: se bloqueou um pedido, como tratou o cache, se enviou cookies.

Para ver os cabeçalhos completos de pedido e resposta, clique em qualquer pedido na aba Network e depois consulte a secção Headers. A vista "Raw" mostra os cabeçalhos exatamente como foram enviados, sem formatação.

Para ver cadeias de redirecionamento, procure pedidos com códigos de estado 3xx. O navegador agrupa-os sob o pedido final, mas pode expandi-los para ver cada passo. É aqui que encontrará loops de redirecionamento, cabeçalhos Location em falta ou redirecionamentos que apontam para o domínio errado.

Para ver tempos, consulte a aba Timing de qualquer pedido. Isto mostra quanto tempo o navegador gastou na resolução DNS, ligação TCP, handshake TLS e espera pelo servidor. Se um redirecionamento estiver lento, a aba Timing indica se o problema é latência de rede ou processamento no servidor.

Uma limitação: o navegador esconde alguns cabeçalhos por motivos de segurança. Os cabeçalhos Set-Cookie são visíveis, mas os valores reais dos cookies são ocultados. Os cabeçalhos Authorization por vezes são escondidos por completo. Se precisar de os ver, use curl.

mitmproxy: o proxy de interceção

mitmproxy é uma ferramenta em Python que fica entre o seu navegador e o servidor, mostrando cada pedido e resposta em tempo real. É mais complexa do que curl, mas é a única ferramenta que mostra o que o navegador realmente envia, incluindo cabeçalhos que o navegador adiciona automaticamente.

Para a iniciar:

mitmproxy

Depois configure o seu navegador para usar localhost:8080 como proxy HTTP. mitmproxy mostrará todos os pedidos numa interface de terminal. Pode inspecionar cabeçalhos, editar pedidos antes de serem enviados ou repetir pedidos com parâmetros diferentes.

Isto é útil para depurar problemas que só acontecem no navegador: pedidos CORS preflight, tratamento de cookies ou pedidos que falham quando determinados cabeçalhos estão presentes. Também é útil para testar como o seu site se comporta atrás de um proxy corporativo ou VPN, porque mitmproxy consegue simular esses ambientes.

A desvantagem é a complexidade de configuração. Tem de instalar um certificado raiz para que mitmproxy possa intercetar tráfego HTTPS, e tem de configurar o navegador para usar o proxy. Para verificações rápidas, curl é mais rápido. Para depuração profunda, mitmproxy vale o tempo de configuração.

webpagetest: perspetiva de produção

WebPageTest é um serviço gratuito que carrega a sua página a partir de navegadores reais em diferentes localizações e mostra a conversa HTTP completa. É mais lento do que curl, mas mostra o que os utilizadores reais experienciam, incluindo comportamento da CDN, resolução DNS e negociação TLS.

As vistas "Request Headers" e "Response Headers" mostram exatamente o que o navegador enviou e recebeu. A vista "Waterfall" mostra o tempo de cada pedido, incluindo redirecionamentos. É aqui que encontrará problemas que só acontecem em determinadas regiões ou em certas redes.

WebPageTest também mostra a cadeia de redirecionamento do documento principal, que é onde vive a maioria dos problemas de redirecionamento. Se o seu site redireciona de http:// para https://, depois de www. para sem www., e depois de / para /en/, WebPageTest mostra os três passos e quanto tempo cada um demorou.

Para ferramentas que o ajudam a validar e otimizar estes fundamentos HTTP, Wux Webtools oferece várias utilidades que correm inteiramente no seu navegador, incluindo analisadores de cabeçalhos e verificadores de redirecionamento que respeitam a sua privacidade ao processar tudo do lado do cliente.

Quando os cabeçalhos mentem

Os problemas HTTP mais difíceis são aqueles em que o servidor envia cabeçalhos contraditórios. Um cabeçalho Cache-Control diz no-cache, mas um cabeçalho Expires diz que o recurso é válido durante um ano. Um cabeçalho Location aponta para um URL relativo, mas o cabeçalho Content-Location aponta para outro lugar. O navegador tem de adivinhar em qual confiar, e navegadores diferentes adivinham de forma diferente.

Quando isto acontece, precisa de ver os cabeçalhos brutos na ordem em que o servidor os enviou. curl -v faz isto. mitmproxy também. As DevTools do navegador por vezes reordenam cabeçalhos para facilitar a leitura, o que esconde o problema.

Outro problema comum: cabeçalhos adicionados por uma CDN ou por um balanceador de carga, e não pela sua aplicação. Se está a depurar um problema de cache, precisa de saber se o cabeçalho Cache-Control veio da sua aplicação ou da CDN. curl mostra o resultado final, mas não indica de onde veio cada cabeçalho. Para isso, precisa de contornar a CDN (acedendo diretamente ao servidor de origem) e comparar os cabeçalhos.

O problema do loop de redirecionamento

Loops de redirecionamento são o problema HTTP mais comum em produção. Acontecem quando dois servidores discordam sobre para onde um URL deve apontar: a CDN redireciona para a origem, a origem redireciona de volta para a CDN. Ou o balanceador de carga redireciona HTTP para HTTPS, mas a aplicação redireciona HTTPS de volta para HTTP porque não vê o cabeçalho X-Forwarded-Proto.

Para depurar isto, precisa de ver a cadeia de redirecionamento completa, incluindo o cabeçalho Location em cada passo. curl -L -v faz isto, mas para após 50 redirecionamentos para evitar loops infinitos. Se está a atingir esse limite, tem um loop de redirecionamento.

A correção costuma ser uma alteração de configuração: indicar à aplicação que confie no cabeçalho X-Forwarded-Proto, ou indicar à CDN que pare de redirecionar pedidos que já são HTTPS. Mas não consegue corrigir o problema até ver o loop, e o navegador não lhe mostrará mais do que alguns redirecionamentos antes de desistir.

O que verificar primeiro

Quando algo falha em produção, verifique estes pontos por esta ordem:

1. Código de estado: É o que esperava? Um 301 é permanente, um 302 é temporário, um 307 preserva o método HTTP. Se está a ver o código errado, o problema está na sua configuração de redirecionamento.

1. Cabeçalho Location: Aponta para o sítio certo? É um URL absoluto ou relativo? URLs relativos são resolvidos em relação ao URL atual, o que pode produzir resultados inesperados se o URL base não for o que pensa.

1. Cabeçalhos de cache: O navegador está a colocar o redirecionamento em cache? Um redirecionamento 301 é colocado em cache por defeito, o que significa que um redirecionamento mal configurado pode quebrar o seu site durante horas mesmo depois de o corrigir. Verifique os cabeçalhos Cache-Control e Expires para ver durante quanto tempo o navegador se lembrará do redirecionamento.

1. Cabeçalhos CORS: Se o pedido for cross-origin, o servidor envia o cabeçalho Access-Control-Allow-Origin correto? Se não, o navegador bloqueará o pedido e verá um erro CORS na consola. Os cabeçalhos de resposta do servidor são o único lugar para corrigir isto — não é possível contorná-lo no navegador.

1. Tempo: Quanto tempo demorou o pedido? Se estiver lento, é latência de rede ou processamento no servidor? As DevTools do navegador e WebPageTest mostram decomposições de tempo que indicam para onde foi o tempo.

Para uma análise mais aprofundada de como o comportamento dos navegadores mudou em torno da privacidade e dos cabeçalhos, veja o que mudou nos cookies em 2026 e o que fazer a esse respeito, que aborda as implicações de cabeçalhos e consentimento das atualizações recentes dos navegadores.

Principais conclusões

• curl -L -v mostra a cadeia de redirecionamento completa e todos os cabeçalhos, sem interpretação do navegador
• A aba Network do navegador mostra o que o navegador fez com a resposta, incluindo decisões de cache e CORS
• mitmproxy mostra o que o navegador enviou, incluindo cabeçalhos que o navegador adiciona automaticamente
• WebPageTest mostra o que utilizadores reais experienciam, incluindo comportamento da CDN e diferenças regionais
• Loops de redirecionamento e cabeçalhos contraditórios são os problemas de produção mais comuns, e são invisíveis sem inspeção HTTP bruta

FAQ

P: Porque é que curl mostra cabeçalhos diferentes dos do navegador?

R: Porque o navegador adiciona cabeçalhos automaticamente (User-Agent, Accept, Cookie) e segue as suas próprias regras de cache e CORS. curl envia apenas aquilo que lhe disser para enviar. Para ver o que o navegador realmente envia, use mitmproxy ou as DevTools do navegador.

P: Como depuro um redirecionamento que só acontece para alguns utilizadores?

R: Verifique se o redirecionamento depende de cabeçalhos que o utilizador envia: User-Agent, Accept-Language, Cookie ou endereço IP (via X-Forwarded-For). Use curl para enviar os mesmos cabeçalhos que o utilizador enviou, ou use WebPageTest para carregar a página a partir da localização do utilizador.

P: Qual é a diferença entre redirecionamentos 301 e 302?

R: Um 301 é permanente e indica ao navegador para colocar o redirecionamento em cache (por vezes para sempre). Um 302 é temporário e indica ao navegador para não o colocar em cache. Se não tem a certeza de qual usar, use 302 — pode sempre alterá-lo para 301 mais tarde.

P: Porque é que o meu redirecionamento funciona em curl, mas não no navegador?

R: Provavelmente porque o navegador está a usar em cache um redirecionamento antigo, ou porque está a bloquear o redirecionamento devido a regras de CORS ou de conteúdo misto. Verifique a consola das DevTools do navegador para erros e verifique os cabeçalhos Cache-Control para ver se o navegador está a usar uma resposta em cache.

P: Como vejo os cabeçalhos que uma CDN adiciona?

R: Use curl para aceder ao URL da CDN e depois use curl novamente para aceder diretamente ao servidor de origem (contornando a CDN). Compare os cabeçalhos. Aqueles que só aparecem na primeira resposta vieram da CDN.

<!-- tool-cta:start -->

💡 Experimente isto: Ao investigar problemas de redirecionamento, o Redirect Checker rastreia toda a cadeia e mostra os códigos de status e cabeçalhos em cada etapa.

<!-- tool-cta:end -->

Fontes

• documentação do curl — Referência oficial das opções de linha de comando e do comportamento de curl
• documentação do HTTPie — Guia da sintaxe e das funcionalidades de httpie
• MDN Web Docs: HTTP redirections — Explicação abrangente dos códigos de estado e do comportamento de redirecionamento HTTP
• documentação do WebPageTest — Como interpretar resultados e cabeçalhos do WebPageTest