Consulta de códigos de status HTTP

Um código de status é o veredito do servidor sobre uma requisição, resumido em um único número, e costuma ser o caminho mais rápido até a causa de uma falha. Ele diz se você deve olhar para a requisição que enviou, para a aplicação que a processou ou para algo que está no meio do caminho. A ferramenta acima transforma esse número nessa resposta.

Como funciona

Digite um código (503), o início de um (40 lista do 400 ao 409) ou parte de um nome (timeout, gateway), ou escolha uma classe pelos botões. Clique em qualquer item para ver o que ele significa. Para os códigos que mais aparecem durante a depuração, como 401, 404, 429, 500 e do 502 ao 504, o painel mostra também o que costuma disparar o código, como corrigi-lo e quais códigos relacionados vale a pena conferir em seguida. Cada item cita a RFC que o define, para você ir direto à fonte quando um detalhe fizer diferença.

A lista cobre todas as entradas permanentes do registro de códigos de status HTTP da IANA, incluindo o 418, que o registro mantém reservado porque a RFC de brincadeira o tornou popular demais para ser reatribuído. Nada do que você digita sai do seu navegador.

Antes de tudo, encontre o código de status

Páginas de erro costumam esconder o número real atrás de uma mensagem amigável, então leia-o na própria resposta:

• Navegador. Abra as ferramentas de desenvolvedor, vá até o painel Rede (Network) e recarregue. Cada requisição mostra o seu status. No Chrome, filtre com status-code:500 ou ordene a coluna para agrupar as falhas.
• Terminal. curl -i imprime a linha de status e os headers antes do corpo. Para obter só o número, algo útil em scripts e health checks, descarte o corpo:

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/api/orders

curl -I é tentador, mas envia uma requisição HEAD, e alguns servidores respondem a HEAD de forma diferente de GET. Quando os dois divergirem, confie no método que a sua aplicação realmente usa.

Uma ordem de triagem que economiza tempo

Comece pelo primeiro dígito. Um 4xx diz que o servidor acha que o problema está na requisição, então confira a URL, o método, as credenciais e o corpo antes de mexer no servidor. Um 5xx diz que o servidor falhou em algo que deveria ter tratado, e a explicação está nos logs dele, não na resposta.

Depois, pergunte quem gerou o código. Um 502 ou 504 raramente é escrito pela sua aplicação. Ele vem do proxy, do load balancer ou da CDN que fica na frente dela, avisando que a aplicação nunca respondeu direito. O header Server e o estilo da página de erro geralmente entregam qual camada foi. Reinicie ou escale o serviço upstream, e confira o timeout do proxy, antes de sair procurando no código da aplicação.

Fique de olho em códigos que não estão no registro. Algumas peças de infraestrutura inventam os seus. O Nginx registra 499 quando o cliente desistiu antes de a resposta ficar pronta, e a Cloudflare retorna de 520 a 526 para problemas de conexão e de TLS com a origem. A ferramenta os mostra como desconhecidos, e essa é justamente a pista: consulte a documentação desse fornecedor, não a especificação HTTP.

Tentar de novo com segurança

Nem toda falha merece uma nova tentativa, e nem toda requisição pode ser repetida com segurança:

• 429 e 503 são um convite para voltar mais tarde. Se a resposta trouxer Retry-After, espere pelo menos esse tempo. Caso contrário, use backoff exponencial com jitter, para que uma frota de clientes não tente de novo ao mesmo tempo.
• 502 e 504 costumam ser passageiros, mas só repita automaticamente se o método for idempotente (GET, HEAD, PUT, DELETE). Um POST que estourou o timeout pode já ter criado o pedido, e repeti-lo às cegas pode criá-lo duas vezes. Chaves de idempotência existem exatamente para esse caso.
• A maioria dos outros 4xx vai falhar do mesmo jeito em toda tentativa. Repetir um 400, 403 ou 422 só aumenta a carga. Corrija a requisição.

Saiba mais

Códigos de status HTTP: referência completa explica cada classe em profundidade, incluindo a semântica de redirecionamento e de cache e os pares que é fácil confundir. Se você está escolhendo os códigos da sua própria API, e não decifrando os de outra, leia Design de APIs REST. Quando um 401 envolve um bearer token, o decodificador de JWT mostra se ele expirou ou se aponta para a audience errada, e o codificador de URL pega as query strings mal escapadas que estão por trás de muitos 400.