Códigos de status HTTP

Códigos de status HTTP são números de três dígitos que um servidor envia de volta na resposta para descrever o resultado da sua requisição. 200 significa que a requisição foi bem-sucedida, 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 em uma das cinco classes — 2xx é sempre sucesso, 5xx é sempre falha do servidor — então saber a classe já te diz onde começar a depurar: no lado do cliente ou no lado do servidor.

O primeiro dígito define a classe: 1xx Informativo (a requisição foi recebida e está em andamento, ex.: 100 Continue), 2xx Sucesso (funcionou, ex.: 200 OK), 3xx Redirecionamento (você precisa ir a outro lugar, ex.: 301 Moved Permanently), 4xx Erro do cliente (sua requisição está errada, ex.: 404 Not Found), e 5xx Erro do servidor (o servidor falhou, ex.: 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 você vai encontrar no dia a dia são 200 OK, 201 Created, 204 No Content, redirecionamentos 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. Ative 'Somente comuns' na ferramenta acima para filtrar a lista completa e chegar apenas a esse conjunto reduzido, com causas e soluções para cada um.

200 OK é a resposta padrão de sucesso — em um GET, retorna o recurso no corpo; em um POST, retorna o resultado da ação. 201 Created significa que um POST ou PUT teve sucesso e criou um novo recurso; o servidor normalmente coloca o endereço desse novo recurso em um cabeçalho Location, ex.: Location: /usuarios/42. Se você estiver construindo uma API e criando um recurso, retorne 201 com um cabeçalho Location — não 200 — para que os clientes saibam onde encontrar o novo objeto.

404 significa que o servidor não encontrou nada naquela URL — ela não existe, foi movida, ou o link está quebrado. Corrija verificando a URL por erros de digitação e capitalização incorreta, adicionando um redirecionamento 301 do endereço antigo para o novo, verificando as regras de roteamento ou reescrita do seu servidor, e entregando uma página 404 personalizada e útil. Ao contrário do 410 Gone, um 404 não garante que o recurso sumiu para sempre, então os mecanismos de busca continuam rastreando-o.

301 Moved Permanently indica que o recurso tem uma nova localização definitiva, então os mecanismos de busca transferem os sinais de ranqueamento para a nova URL e atualizam seu índice — use quando mudar uma URL permanentemente. 302 Found é temporário: a URL original permanece canônica e mantém seu ranqueamento, então use para mudanças de curta duração como testes A/B ou uma página de manutenção. Para requisições não-GET, use 308 (permanente) ou 307 (temporário), pois eles preservam o método HTTP em vez de permitir que navegadores façam downgrade de um POST para um GET.

403 Forbidden significa que o servidor entendeu sua requisição mas se recusa a autorizá-la — e ao contrário do 401, enviar credenciais não vai ajudar. As causas típicas são permissões ou escopos insuficientes na conta, permissões de arquivo erradas no servidor (ex.: um arquivo configurado como 600 em vez de 644), um bloqueio de IP ou regra de WAF, ou listagem de diretório desabilitada sem arquivo index presente. Verifique as funções da conta, as permissões de arquivo e quaisquer listas de permissão. Alguns servidores retornam deliberadamente 403 em vez de 404 para evitar revelar que um recurso existe.

Todos são falhas do servidor 5xx, mas significam coisas diferentes. 500 Internal Server Error é um 'algo quebrou' genérico — geralmente uma exceção não tratada ou bug na aplicação. 502 Bad Gateway significa que um proxy recebeu uma resposta inválida do servidor de aplicação upstream (normalmente ele travou). 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 demais para responder. Comece pelos logs do servidor para distinguir esses casos na prática.

429 significa que você atingiu um limite de taxa — requisições demais em uma determinada janela de tempo. O servidor deve incluir um cabeçalho Retry-After informando quanto tempo esperar. Corrija respeitando esse cabeçalho, adicionando backoff exponencial entre tentativas, fazendo cache de respostas para reduzir o volume de requisições, ou pedindo uma cota maior. É comum em APIs públicas e endpoints de login que se protegem contra abuso. GitHub, Stripe e Twitter/X usam 429 para limitar taxa de acesso à API.

Erros 4xx são culpa do cliente — a própria requisição está errada, então reenviar sem alterações não vai adiantar (400 Bad Request, 401 Unauthorized, 404 Not Found). Erros 5xx são culpa do servidor — sua requisição pode estar perfeitamente correta, mas o servidor não conseguiu atendê-la (500, 502, 503), então a mesma requisição pode ter sucesso quando o servidor se recuperar. Corrija sua requisição para 4xx, corrija o servidor para 5xx. Essa distinção importa para a lógica de retry: faça retry apenas em respostas 5xx com backoff exponencial — fazer retry em 4xx só desperdiça cota de requisições.

Os principais são 200 OK (toda página indexável deve retornar esse), 301 Moved Permanently (passa o ranqueamento para uma nova URL durante migrações), 302 Found (temporário — mantém o ranqueamento na URL original), 404 Not Found e 410 Gone (informam aos rastreadores que a página está faltando; 410 é removido do índice mais rápido porque é permanente), e 503 Service Unavailable (o código seguro para SEO em manutenções planejadas — diz ao Google para voltar depois em vez de desindexar a página).

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

Todos os quatro são redirecionamentos, mas 307 e 308 garantem que o método HTTP original e o corpo sejam preservados, enquanto 301 e 302 historicamente permitem que os clientes mudem um POST para GET na requisição redirecionada. Então 301 (permanente) e 302 (temporário) são ótimos para redirecionamentos simples de página, mas para um endpoint que recebe dados via POST ou PUT, use 308 para mudanças permanentes e 307 para temporárias, para manter o método intacto e evitar perda de dados.

Códigos na faixa 520–530 são códigos não padrão que o Cloudflare retorna quando algo falha entre o Cloudflare e seu servidor de origem — eles não fazem parte da especificação HTTP oficial, mas você 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 conexão (está offline ou bloqueando o Cloudflare), 522 significa que a conexão TCP expirou, 523 significa que a origem está inacessível, 524 significa que a origem conectou mas não respondeu dentro de 100 segundos, 525 e 526 são falhas de handshake SSL e de certificado, e 530 geralmente é um erro de DNS na origem acompanhado de um código 1xxx. Pesquise qualquer um desses números acima para ver causas e soluções.

O MDN Web Docs é a referência de spec autoritativa, mas não tem barra de busca ao vivo, sem filtro por classe e sem visualização compacta de cheat sheet — você navega uma página por código. httpstatuses.com mostra os códigos em uma grade, mas omite causas e soluções práticas. restapitutorial.com cobre convenções REST sem uma busca interativa. HTTP.cat é um site de memes divertido (cada código tem uma foto de gato) mas impraticável para depuração real. Esta ferramenta combina referência pesquisável, filtro por classe, modo cheat sheet, causas e soluções em português, e os códigos Cloudflare 5xx que a maioria das referências ignora — tudo em uma página que roda offline sem anúncios ou cadastro.

Completamente. A lista inteira é entregue como dados estáticos dentro da página, então cada busca, filtro e consulta roda localmente no seu navegador — nada é enviado, registrado ou transmitido a um servidor. Isso também significa que a ferramenta carrega instantaneamente e continua funcionando offline assim que a página estiver aberta. Sem cadastro, sem conta, sem limite de requisições e sem paywall. Só uma referência rápida e privada que funciona tão bem no celular quanto no computador.