Códigos de erro HTTP, e como saber qual está mesmo a ver

Todo o erro HTTP é uma resposta de uma linha a uma pergunta que ninguém fez em voz alta: o que aconteceu ao meu pedido? O número é a resposta inteira, e é deliberadamente seco, por isso a maior parte do trabalho está em saber a que pergunta cada número responde.

É para isso que esta página serve. Não uma lista dos sessenta e tal códigos de estado, a maioria dos quais nunca vai ver, mas a dúzia larga que chega mesmo às pessoas, arrumada pelo que lhe diz sobre onde esteve a falha.

A única divisão que importa

O primeiro dígito é a única parte do código de que precisa de se lembrar.

4xx

O servidor percebeu-o e está a recusar, ou não conseguiu analisar o que chegou. O problema está no pedido

5xx

O pedido estava bem. O servidor não conseguiu produzir uma resposta, ou escolheu não o fazer

Todo o resto decorre daí. Um 4xx manda-o olhar para o que foi enviado: o URL, os cabeçalhos, o corpo, as credenciais. Um 5xx manda-o para os logs do servidor e, se o servidor não é seu, pouco pode fazer além de reportar bem.

A palavra “cliente” em “erro do cliente” é onde as pessoas se perdem, por isso vale a pena dizê-lo com clareza: o cliente não é você. O cliente é o software que compôs o pedido, e num site moderno isso é quase sempre o próprio JavaScript da página. Um 4xx no site de outra pessoa é normalmente o bug dela com o seu nome em cima.

Os códigos 4xx com que vai mesmo topar

400 Bad Request é o servidor a não conseguir sequer analisar o que chegou. É o único desta família que é sobre a forma do pedido em vez de ser sobre permissão ou existência. Um corpo malformado, um content type em falta, um URL não codificado. Há uma única versão que pode corrigir sozinho: um bloco de cookies que cresceu demais, coisa que uma janela privada confirma em segundos.

401 e 403 são os dois que se trocam constantemente. 401 quer dizer que o servidor não sabe quem você é e quer credenciais. 403 quer dizer que sabe exactamente quem você é e a resposta continua a ser não. Mandar melhores credenciais resolve o primeiro e nunca resolve o segundo.

404 Not Found não precisa de explicação, mas uma coisa vale a pena saber-se: um 404 num pedido que a página fez em segundo plano, e não na barra de endereço, normalmente significa que um build ou um deploy perdeu um ficheiro, e não que alguém escreveu mal.

429 Too Many Requests é o único código de estado que é sobre o seu comportamento em vez de ser sobre o servidor ou o recurso. É também o único erro em que tentar de novo piora as coisas, porque uma nova tentativa é mais um pedido para o limitador contar.

Os códigos 5xx, que parecem iguais e significam coisas diferentes

Os quatro dizem “do nosso lado”, e distingui-los decide onde alguém olha primeiro.

500 Internal Server Error

A aplicação correu e o próprio código dela falhou. Uma excepção não tratada. Respondeu, e a resposta foi um erro que fez sozinha

502 Bad Gateway

Um servidor da frente recebeu uma resposta inutilizável da aplicação que tem atrás. A falha está entre dois servidores

503 Service Unavailable

Alguma coisa escolheu não o servir. Manutenção, capacidade, um limitador de taxa, ou nada saudável para onde encaminhar

504 Gateway Timeout

A aplicação nunca respondeu a tempo. O servidor da frente desistiu de esperar

O atalho útil: um 500 é código a partir-se enquanto corre, um 502 é um proxy que não conseguiu uma boa resposta, um 504 é a aplicação demasiado lenta, e um 503 é o único que normalmente é de propósito. Essa última distinção importa mais do que parece: um 503 traz muitas vezes um cabeçalho Retry-After a dizer exactamente quando voltar, e quase ninguém o lê.

Os erros que não são códigos de estado de todo

Algumas das falhas mais comuns nunca produzem um código de estado, e é precisamente por isso que baralham. O pedido não falhou; nunca chegou a completar-se.

TypeError: Failed to fetch é o erro menos informativo do JavaScript. Não há estado para ler porque o pedido nunca chegou suficientemente longe para ter um.

Os erros CORS são o navegador a recusar entregar ao seu código uma resposta que até chegou. O servidor respondeu perfeitamente; apenas não disse que a sua origem era permitida.

ERR_CONNECTION_REFUSED, RESET, CLOSED e TIMED_OUT acontecem inteiramente abaixo do HTTP. Cada um nomeia até onde a ligação chegou antes de morrer, o que é a maior parte de um diagnóstico de borla.

O conteúdo misto é o navegador a bloquear um recurso inseguro numa página segura. Não falhou nada na rede; foi aplicada uma regra.

Ler um que não é seu

Se é visitante e não a pessoa que pode corrigir, três verificações separam a maioria dos casos e levam menos de um minuto.

Recarregue uma vez. Uma boa parte dos 500 e dos 503 é um único mau momento. Se se resolver, não há nada a perseguir.

Experimente uma janela privada. É o teste para a família dos cookies e dos cabeçalhos: um 400 que desaparece em privado era um bloco de cookies grande demais, e um que não desaparece nunca foi seu.

Experimente outra rede. Um telemóvel com dados responde à pergunta que um limitador de taxa levanta. Se o erro o segue para todo o lado é a sua conta ou o site; se desaparece, era o endereço de onde vinha. É a mesma pergunta que distinguir o seu bug da falha deles, feita depressa.

Porque é que o código sozinho raramente chega para corrigir seja o que for

Cada erro acima é um resumo a que foram tiradas as provas. Não é acidente: um 500 é vago de propósito, porque o stack trace fica no servidor, e um 400 não lhe vai dizer que cabeçalho o ofendeu. O código nomeia a categoria e cala o caso.

Por isso “apanhei um 500” é um relato que quase nada diz a um programador e, quando alguém investiga, o pedido que falhou já desapareceu. O que fecha um depressa é o próprio pedido falhado, a sua hora exacta, e o que a pessoa estava a fazer.

O registo de rede é onde um código de estado deixa de ser uma categoria e passa a ser um caso: o pedido que apanhou o erro, os seus cabeçalhos e o seu corpo, e o minuto exacto, para que quem lhe pegue o possa cruzar com um log do servidor em vez de reproduzir tudo primeiro.

Num parágrafo

O primeiro dígito é a divisão que importa: um 4xx significa que o problema está no pedido, um 5xx que o servidor não conseguiu responder, e o “cliente” culpado por um 4xx é normalmente o próprio JavaScript do site e não você. Dentro dos 4xx, o 400 é sobre a forma do pedido, o 401 e o 403 sobre identidade contra permissão, e o 429 sobre com que frequência pediu. Dentro dos 5xx, o 500 é código a partir-se, o 502 um proxy com uma resposta má, o 504 nada que responda a tempo, e o 503 o único que normalmente é uma decisão. Os erros sem código de estado nenhum, como failed to fetch, CORS, ERR_CONNECTION_* ou o conteúdo misto, são os que mais baralham, porque o pedido nunca se completou em vez de falhar. Seja qual for o seu, o código nomeia a categoria e cala o caso, por isso capture o pedido falhado enquanto ainda o tem.