Códigos de estado HTTP explicados: os que realmente se confundem

O primeiro dígito é a única parte que alguns clientes leem

A RFC 9110 exige que um cliente compreenda a classe de um código de estado mesmo sem reconhecer o código em si, e que trate qualquer código desconhecido como o x00 da sua classe. Um cliente que nunca ouviu falar do 451 trata-o como um 400; um 599 desconhecido é tratado como um 500. É essa regra que torna o espaço extensível, e também significa que a classe carrega quase todo o comportamento: as caches decidem a partir dela se guardam, os proxies se repetem e os rastreadores se indexam, quase sempre antes de analisarem seja o que for do seu corpo de resposta.

A consequência prática é que devolver um 200 com o erro descrito no corpo coloca a falha onde mais nada a vê. A sua sonda de disponibilidade fica verde, o seu CDN guarda a página de erro em cache e um motor de busca indexa-a como um documento real. É o problema do soft 404 na sua forma geral, e vale a pena auditá-lo, porque a correção é uma linha no código de estado e não algo arquitetural.

Redireções: quais conservam o seu POST

A grelha dos quatro códigos de redireção cruza na verdade duas perguntas: permanente ou temporária, e o método sobrevive. 301 e 308 são permanentes, 302 e 307 temporárias; 307 e 308 são os dois que proíbem o cliente de alterar o pedido. A MDN é direta sobre a razão do par recente: o 301 já exigia que método e corpo ficassem inalterados, mas essa exigência era mal tratada pelos clientes antigos, que passavam a GET. Ninguém conseguia corrigir o parque instalado, por isso cunharam-se dois códigos novos com a garantia escrita na definição.

A escolha decorre portanto do tráfego. Para uma página que só recebe GET, o 301 serve e é aquilo a que os motores de busca estão mais habituados. Para um caminho de API, o destino de um formulário ou qualquer coisa que possa receber POST, PUT ou DELETE, use 308 e o pedido chega intacto. Um aviso sobre a permanência: os navegadores guardam um 301 em cache de forma agressiva e alguns mantêm-no muito mais tempo do que espera, pelo que um 301 emitido durante uma experiência pode sobreviver-lhe em máquinas a que não tem acesso. Sirva 302 ou 307 enquanto ainda decide.

Os erros mais vezes devolvidos de forma errada

401 e 403 são o par que mais tempo de suporte custa. O 401 significa que o pedido não trazia credenciais de autenticação válidas, e a MDN nota que é enviado com um cabeçalho WWW-Authenticate que descreve o esquema que o servidor espera — é um convite a tentar de novo com credenciais. O 403 é a situação oposta: as credenciais são perfeitamente válidas e o cliente continua sem permissão para esta ação. Devolver um 401 a um utilizador autenticado diz ao cliente dele para se reautenticar, o que produzirá exatamente a mesma recusa, e leva-o a pensar que a sessão está partida quando não está.

404 e 410 diferem apenas no grau de certeza, e é esse o ponto. A orientação da MDN é explícita: se quem opera o servidor não sabe se a condição é temporária ou permanente, deve usar 404. O 410 usa-se quando retirou a coisa de propósito e ela não volta — é cacheável por omissão e diz aos rastreadores para deixarem de perguntar. O Retry-After, por seu lado, é um cabeçalho que leva um atraso em segundos ou uma data HTTP; num 503 estima quanto tempo o serviço estará indisponível e num 429 indica quanto esperar antes de um novo pedido. É orientação, não contrato, e a MDN nota que o suporte entre clientes é desigual — mas o Googlebot respeita-o, o que já justifica defini-lo durante uma manutenção planeada.

Perguntas frequentes

Uma migração de site deve usar 301 ou 308?

Para páginas que só são pedidas com GET, o 301 é o valor seguro e aquele que todos os rastreadores e proxies tratam há décadas. Recorra ao 308 em tudo o que possa receber POST, PUT ou DELETE — pontos de formulário, rotas de API, recetores de webhooks — porque é aí que um cliente a rebaixar o método em silêncio transforma uma redireção num corpo de pedido perdido. Nada impede usar ambos na mesma migração, rota a rota.

O que deve uma API devolver quando a validação falha?

Use 400 Bad Request quando o próprio pedido está malformado e o servidor não o consegue analisar — JSON partido, um cabeçalho obrigatório em falta. Use 422 Unprocessable Content quando a sintaxe está correta mas o conteúdo quebra as suas regras, como um corpo bem formado com uma data de fim anterior à de início. O que não deve devolver é um 500, que culpa o servidor por um erro do cliente e polui o seu orçamento de erros, nem um 200 com o problema descrito no corpo, que esconde a falha de todas as camadas entre si e quem chama.

Os 404 prejudicam o posicionamento?

Um 404 é uma resposta válida e honesta, e uma parte normal de qualquer site com algum tempo; uma página que já não existe deve dizê-lo. O dano vem dos substitutos. Um soft 404 — uma página simpática servida com estado 200 — mantém URLs mortos no índice e gasta orçamento de rastreio em nada. Redirecionar em bloco todas as páginas em falta para a homepage é o mesmo erro disfarçado de 301. Se a remoção foi deliberada e permanente, o 410 di-lo com clareza.