Pesquisa de Código de Status HTTP

O HTTP Status Code Lookup fornece acesso instantâneo a explicações detalhadas para todo código de status HTTP de resposta de 100 a 599, incluindo referências RFC, casos de uso comuns e as distinções sutis entre códigos frequentemente confundidos. Digite um código como 403 ou procure por palavra-chave como "redirect" para obter o nome oficial, significado e orientação prática para quando usá-lo em suas próprias APIs.

Entendendo Códigos de Status HTTP

Todo resposta HTTP começa com um código de status de três dígitos que diz ao cliente o que aconteceu com sua solicitação. Se você alguma vez viu uma página 404, recebeu um erro 500 de uma API ou foi silenciosamente redirecionado por um 301, você encontrou códigos de status em ação. Eles são a primeira coisa que seu navegador, cliente HTTP ou sistema de monitoramento verifica quando uma resposta chega, e escolher o código certo em suas próprias APIs é essencial para construir sistemas que se comportam previsível e são fáceis de debugar.

Códigos de status são agrupados em cinco classes por seu primeiro dígito. Os códigos 1xx são informativos -- o servidor está reconhecendo a solicitação mas não terminou de processá-la. Os códigos 2xx indicam sucesso -- a solicitação foi recebida, entendida e processada corretamente. Os códigos 3xx lidam com redirects -- o cliente precisa tomar ação adicional, geralmente seguindo uma nova URL. Os códigos 4xx sinalizam erros de cliente -- a solicitação foi malformada, não autorizada ou apontava para algo que não existe. E os códigos 5xx indicam erros de servidor -- o servidor entendeu a solicitação mas falhou em processá-la devido a um problema interno.

O desafio não é saber que 200 significa sucesso ou 404 significa não encontrado -- esses são bem conhecidos. A complexidade real está nas distinções sutis. Você deve usar 401 ou 403 quando um usuário falta permissão? É 301 ou 308 o redirect certo para um endpoint POST que se moveu? Uma busca sem resultados deve retornar 200 com corpo vazio, 204 ou 404? Esta ferramenta explica essas distinções com orientação prática para que você possa fazer a escolha certa para seu caso de uso específico.

Como Procurar um Código de Status HTTP

1. Digite um número de código de status (ex: 404) ou procure por palavra-chave (ex: "redirect", "unauthorized").
2. Veja o nome oficial, referência RFC e explicação detalhada.
3. Leia orientação de caso de uso para quando retornar esse código em sua própria API.

Referência Rápida de Código de Status HTTP

Informacional (1xx)

Sucesso (2xx)

Redirecionamento (3xx)

Erro de Cliente (4xx)

Erro de Servidor (5xx)

Códigos de Status Frequentemente Confundidos

301 vs. 302 vs. 307 vs. 308

• 301 Moved Permanently -- Use quando a URL de um recurso mudou para sempre. Navegadores e mecanismos de busca podem mudar POST para GET no redirect.
• 302 Found -- Redirect temporário. Historicamente, navegadores mudavam POST para GET apesar da spec dizer que não deveriam. Ambíguo na prática.
• 307 Temporary Redirect -- Como 302, mas o navegador deve preservar o método HTTP original (POST permanece POST).
• 308 Permanent Redirect -- Como 301, mas o navegador deve preservar o método HTTP original. Use isso em vez de 301 quando redirecionando envios de formulário.

401 vs. 403

• 401 Unauthorized -- O cliente não forneceu credenciais de autenticação válidas. A resposta deve incluir um cabeçalho WWW-Authenticate indicando o esquema de autenticação esperado.
• 403 Forbidden -- O cliente está autenticado (ou autenticação não é requerida), mas não tem permissão para acessar o recurso. Re-autenticar não ajudará.

404 vs. 410

• 404 Not Found -- O recurso não está disponível. Pode nunca ter existido ou pode existir no futuro.
• 410 Gone -- O recurso existiu previamente mas foi intencionalmente e permanentemente removido. Mecanismos de busca desindexarão a URL mais rápido com 410 do que 404.

500 vs. 502 vs. 503 vs. 504

• 500 -- O servidor em si encontrou um erro processando a solicitação (exceção não tratada, bug).
• 502 -- Um reverse proxy ou load balancer recebeu uma resposta inválida de um servidor upstream.
• 503 -- O servidor está temporariamente incapaz de lidar com solicitações (sobrecarregado, em manutenção). Frequentemente inclui um cabeçalho Retry-After.
• 504 -- Um reverse proxy ou load balancer expirou esperando uma resposta de servidor upstream.

Quando Usar Esta Ferramenta

• Projetando APIs RESTful -- Escolha códigos de status semanticamente corretos para cada endpoint e condição de erro.
• Debugando respostas de API -- Entenda o que um código de status desconhecido ou inesperado significa em logs do servidor.
• Tratando redirects -- Determine se deve usar 301, 302, 307 ou 308 para seu cenário de redirect específico.
• Configurando alertas de monitoramento -- Configure alertas para códigos de status específicos com entendimento do que cada um indica.
• Otimização SEO -- Use os códigos de redirect corretos (301 vs 302) para preservar rankings em mecanismos de busca durante migrações de URL.
• Triagem de incidente -- Identifique rapidamente se um erro 5xx vem de sua aplicação (500) ou da infraestrutura (502, 504).

Orientação Prática para Códigos de Status de API

Um dos erros mais comuns no design de API é usar excessivamente 200 OK para tudo, incluindo erros. Algumas APIs retornam 200 com mensagem de erro no corpo, forçando o cliente a analisar a resposta para determinar se a solicitação realmente sucedeu. Isso quebra as ferramentas padrão HTTP, torna o monitoramento não confiável e confunde desenvolvedores que esperam que códigos de status HTTP reflitam o resultado real. Use 200 para sucesso, 4xx para erros de cliente e 5xx para erros de servidor -- é para isso que os códigos servem.

Outra frequente fonte de confusão é a escolha entre 404 e respostas de sucesso vazias. Se um usuário procura por produtos e a busca retorna zero resultados, a resposta correta é 200 com array vazio -- o endpoint de busca existe, funcionou e não encontrou nada. Se o usuário solicita um produto específico por ID e esse produto não existe, a resposta correta é 404 -- o recurso que ele solicitou não está lá. A distinção é entre "Fiz o que você pediu e a resposta é nada" (200) versus "a coisa que você pediu não existe" (404).

Para APIs que servem usuários autenticados e não autenticados, cuidado com as informações que você vaza através de códigos de status. Responder com 403 para uma solicitação não autorizada de /admin/users confirma que o endpoint existe. Responder com 404 em vez disso revela nada sobre sua estrutura de URL. A comunidade de segurança chama isso de "segurança através de obscuridade" e tem limites, mas é uma medida de defesa em profundidade razoável para endpoints sensíveis.

Perguntas Frequentes

Quais são os códigos customizados 5xx do CloudFlare?

CloudFlare usa códigos 520 através 527 para problemas entre seus servidores de borda e servidores de origem. Por exemplo, 520 significa que a origem retornou uma resposta inesperada, 521 significa que o servidor web de origem está inativo, 522 significa que a conexão com a origem expirou e 524 significa que a origem respondeu mas demorou demais.

Há diferença entre "Unauthorized" e "Unauthenticated"?

Tecnicamente, HTTP 401 deveria ser chamado "Unauthenticated" porque significa que o cliente não provou sua identidade. O nome "Unauthorized" é um nome histórico errado na spec. A verdadeira falha de autorização (você está autenticado mas falta permissão) é 403 Forbidden.

Devo usar 404 ou 204 quando uma busca retorna nenhum resultado?

Use 200 com um conjunto de resultados vazio. O recurso (o endpoint de busca) existe e respondeu com sucesso -- apenas não encontrou itens correspondentes. Reserve 404 para quando o endpoint em si não existe.

Quando devo usar 429 Too Many Requests?

Use 429 quando um cliente excedeu o limite de taxa de sua API. Inclua um cabeçalho Retry-After indicando quantos segundos o cliente deve esperar antes de tentar novamente. Também inclua cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining para que clientes vejam seu status de quota atual sem atingir o limite.

Qual é a diferença entre 502 e 504 em uma configuração de reverse proxy?

Um 502 Bad Gateway significa que o proxy recebeu uma resposta do servidor upstream, mas a resposta era inválida ou malformada (por exemplo, o upstream retornou dados lixo ou fechou a conexão no meio da resposta). Um 504 Gateway Timeout significa que o proxy nunca recebeu uma resposta -- o servidor upstream não respondeu dentro do período de timeout configurado. Ambos indicam problemas upstream, mas 504 tipicamente sugere que o upstream está sobrecarregado ou inacessível, enquanto 502 sugere que está respondendo mas se comportando incorretamente.

Devo retornar 201 Created ou 200 OK após criar um recurso?

Use 201 Created para solicitações POST que criam um novo recurso. Inclua um cabeçalho Location apontando para a URL do recurso recém-criado. Isso segue convenções REST e ajuda clientes a localizar o novo recurso sem analisar o corpo da resposta. Use 200 para atualizações de recursos existentes (PUT/PATCH).

Ferramentas Relacionadas

• HTTP Header Formatter - Analise e formate cabeçalhos de resposta HTTP que acompanham códigos de status
• CORS Header Explainer - Entenda erros CORS que produzem códigos de status específicos
• MIME Type Lookup - Procure cabeçalhos Content-Type retornados com respostas HTTP
• Cookie Header Parser - Analise cabeçalhos Set-Cookie de respostas HTTP
• curl Command Builder - Construa comandos curl para testar endpoints e inspecionar códigos de status