Códigos de status 4xx explicados: o que os erros de cliente realmente significam

O que a classe 4xx diz

A RFC 9110 define a classe 4xx como "Erro do Cliente": o servidor acredita que o cliente errou. Isso cobre uma requisição para algo que não existe, uma requisição sem as credenciais que precisa, uma requisição que o servidor recusa por motivos de política, e uma requisição malformada ou grande demais.

Três propriedades da classe importam enquanto você está depurando uma:

• Um 4xx é uma resposta final para aquela requisição como foi enviada. Repetir a requisição idêntica normalmente vai produzir o código idêntico.
• O corpo da resposta é feito para ser uma explicação legível por humanos. É por isso que páginas de erro personalizadas existem, e por que uma página 404 vazia é uma oportunidade desperdiçada.
• Algumas respostas 4xx são armazenáveis em cache por padrão. A RFC 9111 lista 404, 405, 410 e 414 entre os códigos que um cache pode guardar de forma heurística, então um 404 errado pode sobreviver ao bug que o causou.

Os códigos 4xx que você vai encontrar

• 400 Bad Request: a requisição está malformada e o servidor não consegue interpretá-la. Frequentemente uma query string ruim, um cabeçalho de cookie grande demais ou um proxy quebrado na frente da aplicação.
• 401 Unauthorized: autenticação é exigida e está ausente ou inválida. O servidor precisa enviar um cabeçalho WWW-Authenticate dizendo ao cliente como se autenticar.
• 403 Forbidden: o servidor entendeu a requisição e a recusa. Credenciais não vão ajudar, porque a recusa é uma decisão de política, não uma falha de autenticação.
• 404 Not Found: nenhuma representação atual existe naquela URL, ou o servidor não vai admitir que existe uma. Coberto em detalhe no guia do 404.
• 405 Method Not Allowed: a URL existe mas não para aquele método. O servidor precisa listar os métodos que aceita em um cabeçalho Allow.
• 408 Request Timeout: o cliente demorou demais para enviar a requisição. Diferente de um 504, onde o atraso está atrás do servidor.
• 410 Gone: o recurso existia e foi removido deliberadamente, e isso é esperado ser permanente.
• 413 Content Too Large e 414 URI Too Long: a requisição excedeu um limite configurado, geralmente um teto de upload ou um limite de tamanho de cabeçalho.
• 429 Too Many Requests: um limite de taxa foi atingido. Esse morde configurações de monitoramento em particular.

Quando um 4xx é na verdade uma configuração errada do servidor

O rótulo "erro do cliente" é sobre papéis de protocolo, não sobre culpa. A maioria dos códigos 4xx que aparecem em um site de produção saudável é causada por algo do seu lado. Uma regra de reescrita ou roteamento que não bate mais transforma URLs válidas em 404s em todo um diretório, e o sinal é um 404 em muitas URLs de uma vez em vez de em uma só. Um build que para de gerar um recurso com hash faz a mesma coisa no nível de arquivo: toda página solicita um arquivo que devolve 404, então a página renderiza mas parece quebrada.

Camadas de segurança respondem pela maior parte do resto. Uma regra de WAF, um filtro de bot ou um bloqueio geográfico pode devolver 403 para tráfego real, e essas são fáceis de perder porque geralmente passam para o endereço IP do escritório. Uma mudança de autenticação que deixa uma página respondendo 401 quando deveria ser pública é um 4xx causado inteiramente pelo servidor. Assim como um 400 ou 413 de um proxy reverso cujo limite de cabeçalho ou corpo é menor que o da aplicação, para uma requisição que a aplicação teria aceitado.

Como diagnosticar um 4xx no seu próprio site

1. Leia o código exato e os cabeçalhos primeiro. Não julgue pela página de erro, que pode ser genérica:

   curl -sS -o /dev/null -D - https://example.com/broken-page

   Isso mostra a linha de status mais Allow, WWW-Authenticate, Retry-After e qualquer cabeçalho de identificação do servidor ou CDN.
2. Decida se é uma URL ou um padrão. Uma URL aponta para um link ou uma página apagada. Um prefixo de caminho inteiro aponta para roteamento, permissões ou uma implantação.
3. Verifique quem respondeu. Compare a resposta da borda da CDN com a resposta da origem. Um 403 que existe só na borda é uma regra de WAF ou de bot, não a sua aplicação.
4. Tente uma identidade de cliente diferente. Um user agent diferente, uma sessão não autenticada ou uma rede diferente pode mudar o código de 403 para 200, o que localiza o bloqueio imediatamente.
5. Leia a linha de log do servidor para aquela requisição. Logs do servidor web e da aplicação registram qual regra ou handler produziu o código. Esse é o passo que geralmente encerra a investigação.
6. Corrija, depois limpe os caches. Como vários códigos 4xx são armazenáveis em cache, uma página corrigida pode continuar servindo o erro antigo a partir de um cache de CDN ou navegador até que a entrada seja invalidada.

Encontrando as páginas 4xx que você nunca visita

Um 4xx não derruba um servidor, e é por isso que passa despercebido. O site carrega, a página inicial está bem, e uma seção devolve 404 ou 403 para todo mundo menos você. Uma verificação HTTP agendada compara o código que recebe contra o código que você espera, então uma página que começa a responder 403 em vez de 200 gera um alerta em vez de esperar por um chamado de suporte. De onde a verificação roda também importa. A HostTracker verifica a partir de mais de 300 pontos de verificação em 158 cidades, então um bloqueio geográfico ou uma regra regional de WAF aparece como uma diferença real entre localidades em vez de um mistério. Se o código que está falhando é 500, 502 ou 503 em vez disso, a causa está do lado do servidor e o guia da família 5xx é o lugar para começar.