Códigos de estado HTTP

Os códigos de estado HTTP são números de três dígitos que o servidor envia de volta na resposta para descrever o resultado do seu pedido. 200 significa que o pedido foi bem-sucedido, 404 significa que a página não foi encontrada, e 500 significa que o servidor encontrou um erro. O primeiro dígito agrupa o código numa de cinco classes — 2xx é sempre sucesso, 5xx é sempre uma falha do servidor — por isso conhecer a classe diz-lhe imediatamente por onde começar a depurar: lado do cliente ou lado do servidor.

O primeiro dígito define a classe: 1xx Informativo (o pedido foi recebido e está a continuar, por exemplo, 100 Continue), 2xx Sucesso (funcionou, por exemplo, 200 OK), 3xx Redireccionamento (precisa de ir para outro local, por exemplo, 301 Moved Permanently), 4xx Erro do cliente (o seu pedido está errado, por exemplo, 404 Not Found), e 5xx Erro do servidor (o servidor falhou, por exemplo, 500 Internal Server Error). Filtre por qualquer classe na ferramenta acima para ver apenas esse grupo com explicações de cada código.

Os que encontrará diariamente são 200 OK, 201 Created, 204 No Content, redireccionamentos 301 e 302, 304 Not Modified, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway e 503 Service Unavailable. Active 'Apenas comuns' na ferramenta acima para filtrar a lista completa até este conjunto reduzido, com causas e soluções para cada um.

200 OK é a resposta de sucesso padrão — para um GET devolve o recurso no corpo, para um POST devolve o resultado da acção. 201 Created significa que um POST ou PUT foi bem-sucedido e criou um novo recurso; o servidor normalmente coloca o endereço desse novo recurso num cabeçalho Location, por exemplo, Location: /users/42. Se estiver a construir uma API e a criar um recurso, devolva 201 com um cabeçalho Location — não 200 — para que os clientes saibam onde encontrar o novo objecto.

404 significa que o servidor não encontrou nada nesse URL — não existe, foi movido, ou a ligação está quebrada. Resolva verificando o URL em busca de erros ortográficos e capitalização incorrecta, adicionando um redireccionamento 301 do endereço antigo para o novo, verificando as regras de encaminhamento ou reescrita do servidor, e disponibilizando uma página 404 personalizada e útil. Ao contrário do 410 Gone, um 404 não garante que o recurso tenha desaparecido para sempre, por isso os motores de pesquisa continuam a rastreá-lo. O MDN Web Docs cobre bem as especificações, mas esta ferramenta mostra as causas comuns e as soluções ao lado de cada código.

301 Moved Permanently indica que o recurso tem uma nova localização definitiva, por isso os motores de pesquisa transferem os sinais de classificação para o novo URL e actualizam o seu índice — use-o quando alterar um URL permanentemente. 302 Found é temporário: o URL original permanece canónico e mantém a sua classificação, por isso use-o para movimentos de curta duração como testes A/B ou páginas de manutenção. Para pedidos que não sejam GET, use 308 (permanente) ou 307 (temporário), porque preservam o método HTTP em vez de permitir que os browsers convertam um POST num GET.

403 Forbidden significa que o servidor compreendeu o seu pedido mas recusa-se a autorizá-lo — e ao contrário do 401, enviar credenciais não vai ajudar. As causas típicas são permissões ou âmbitos insuficientes na conta, permissões de ficheiro incorrectas no servidor (por exemplo, um ficheiro definido como 600 em vez de 644), um bloqueio de IP ou regra WAF, ou uma listagem de directório desactivada sem ficheiro de índice presente. Verifique as funções da conta, as permissões de ficheiro e quaisquer listas de permissões. Alguns servidores devolvem deliberadamente 403 em vez de 404 para evitar revelar que um recurso existe.

Todos são falhas do servidor 5xx, mas com significados diferentes. 500 Internal Server Error é um genérico 'algo correu mal' — normalmente uma excepção não tratada ou um erro na aplicação. 502 Bad Gateway significa que um proxy recebeu uma resposta inválida do servidor de aplicação upstream (frequentemente porque este falhou). 503 Service Unavailable significa que o servidor está temporariamente indisponível ou sobrecarregado — deve incluir um cabeçalho Retry-After. 504 Gateway Timeout significa que o upstream era acessível mas demorou demasiado a responder. Comece pelos registos do servidor para distinguir estes casos na prática.

429 significa que atingiu um limite de pedidos — demasiados pedidos numa determinada janela temporal. O servidor deve incluir um cabeçalho Retry-After a indicar quanto tempo deve aguardar. Resolva respeitando esse cabeçalho, adicionando recuo exponencial entre novas tentativas, colocando respostas em cache para reduzir o volume de pedidos, ou solicitando uma quota maior. É comum em APIs públicas e em endpoints de autenticação que se protegem contra abusos. O GitHub, Stripe e Twitter/X utilizam todos o 429 para limitar pedidos à API.

Os erros 4xx são da responsabilidade do cliente — o pedido em si está errado, por isso reenviar o mesmo pedido não vai ajudar (400 Bad Request, 401 Unauthorized, 404 Not Found). Os erros 5xx são da responsabilidade do servidor — o seu pedido pode ser perfeitamente válido, mas o servidor não conseguiu processá-lo (500, 502, 503), por isso o mesmo pedido pode ser bem-sucedido assim que o servidor recuperar. Corrija o pedido para erros 4xx, corrija o servidor para erros 5xx. Esta distinção é importante para a lógica de novas tentativas: só deve tentar novamente em respostas 5xx com recuo exponencial — tentar novamente num 4xx apenas consome quota de pedidos sem qualquer benefício.

Os principais são 200 OK (todas as páginas que quer indexadas devem devolver este código), 301 Moved Permanently (transfere a classificação para um novo URL durante migrações), 302 Found (temporário — mantém a classificação no URL original), 404 Not Found e 410 Gone (informam os rastreadores que uma página não existe; o 410 é removido do índice mais rapidamente porque é permanente), e 503 Service Unavailable (o código SEO-seguro para manutenção planeada — indica ao Google para regressar mais tarde em vez de remover a página do índice).

401 Unauthorized significa na prática 'não autenticado' — não provou quem é, por isso enviar credenciais válidas (um token, chave de API, ou sessão de autenticação) pode resolver o problema; o servidor deve responder com um cabeçalho WWW-Authenticate. 403 Forbidden significa que está autenticado mas simplesmente não tem autorização para aceder a este recurso — melhores credenciais não vão ajudar, precisa de permissões diferentes. Regra prática: 401 = quem é você, 403 = não pode fazer isso.

Todos os quatro são redireccionamentos, mas 307 e 308 garantem que o método HTTP original e o corpo do pedido são preservados, enquanto 301 e 302 historicamente permitem aos clientes converter um POST num GET no pedido redireccionado. Por isso, 301 (permanente) e 302 (temporário) são adequados para redireccionamentos de páginas simples, mas para um endpoint que recebe dados POST ou PUT, use 308 para movimentos permanentes e 307 para movimentos temporários, de modo a manter o método intacto e evitar perda de dados.

Os códigos no intervalo 520–530 são códigos não normalizados que o Cloudflare devolve quando algo falha entre o Cloudflare e o seu servidor de origem — não fazem parte das especificações HTTP oficiais, mas vai vê-los constantemente atrás do Cloudflare. 520 significa que a origem enviou uma resposta vazia ou inesperada, 521 significa que a origem recusou a ligação (está inactiva ou a bloquear o Cloudflare), 522 significa que a ligação TCP expirou, 523 significa que a origem é inacessível, 524 significa que a origem estabeleceu ligação mas não respondeu dentro de 100 segundos, 525 e 526 são falhas de handshake SSL e de certificado, e 530 é normalmente um erro de DNS na origem acompanhado de um código 1xxx. Pesquise qualquer um destes números acima para ver causas e soluções.

O MDN Web Docs é a referência de especificações autoritativa, mas não tem barra de pesquisa em tempo real, sem filtro por classe, e sem vista de cheat sheet compacta — navega-se uma página por código. O httpstatuses.com mostra os códigos numa grelha, mas omite causas e soluções práticas. O restapitutorial.com cobre convenções REST sem pesquisa interactiva. O HTTP.cat é um site de memes divertido (cada código corresponde à foto de um gato) mas impraticável para depuração real. Esta ferramenta combina uma referência pesquisável, filtro por classe, modo cheat sheet, causas e soluções em linguagem simples, e os códigos Cloudflare 5xx que a maioria das referências ignora — tudo numa única página que funciona offline sem anúncios ou registo.

Completamente. A lista completa é carregada como dados estáticos na página, por isso cada pesquisa, filtro e consulta é executado localmente no seu browser — nada é enviado, registado ou transmitido para um servidor. Isso também significa que carrega instantaneamente e continua a funcionar offline depois de a página estar aberta. Sem registo, sem conta, sem limite de pedidos, e sem paywall. Apenas uma referência rápida e privada que funciona tão bem no telemóvel como no computador.