Os códigos de status HTTP são a linguagem que servidores web usam para comunicar o resultado de uma requisição. Usá-los corretamente é essencial para garantir que APIs e sites funcionem de forma previsível, segura e amigável tanto para usuários quanto para buscadores. Neste guia, você vai aprender as boas práticas mais importantes, os erros comuns ao implementar esses códigos e como sua aplicação pode se beneficiar de uma escolha precisa.

O que são HTTP status codes e por que eles importam?

Toda vez que seu navegador ou aplicativo faz uma requisição a um servidor, ele recebe uma resposta com três dígitos. Esses números indicam se a requisição foi bem-sucedida (2xx), se houve redirecionamento (3xx), erro do cliente (4xx) ou erro do servidor (5xx). Usar o código certo evita ambiguidades, melhora a experiência do usuário e ajuda ferramentas como buscadores a interpretar seu site corretamente. Para consultar todos os códigos de forma rápida, você pode usar nossa ferramenta HTTP status codes, que organiza as classes de 1xx a 5xx com filtros por categoria.

Boas práticas para cada classe de código

1xx – Informativos (raro, mas útil)

Códigos como 100 Continue e 102 Processing são usados principalmente em protocolos avançados (WebDAV, uploads grandes). Evite usá-los em respostas simples — a maioria dos clientes não os trata bem.

2xx – Sucesso (seu alvo principal)

  • 200 OK – Resposta padrão para requisições bem-sucedidas. Úselo para GET que retorna dados ou POST que criou um recurso e já retorna o corpo.
  • 201 Created – Após criar um recurso via POST ou PUT. Inclua o cabeçalho Location com a URL do novo recurso.
  • 204 No Content – Para ações que não precisam retornar corpo (ex.: DELETE bem-sucedido, atualização parcial via PATCH sem retorno).

Exemplo prático: Ao cadastrar um usuário, retorne 201 Created com a URL do perfil no cabeçalho Location. Nunca use 200 para indicar criação — isso confunde clientes que esperam um recurso já existente.

3xx – Redirecionamento (use com cuidado)

  • 301 Moved Permanently – Indica que a URL mudou de forma definitiva. Buscadores atualizam seus índices.
  • 302 Found – Redirecionamento temporário. Use para manutenção ou quando o recurso pode voltar ao original.
  • 303 See Other – Para redirecionar após um POST (padrão Post/Redirect/Get). Evita reenvio acidental do formulário.
  • 307/308 – Mantêm o método HTTP original (útil para APIs que exigem o mesmo verbo).

Erro comum: Usar 301 para redirecionamentos temporários pode prejudicar o SEO, pois buscadores tratam como permanente. Sempre avalie a intenção.

4xx – Erro do cliente (seja claro)

  • 400 Bad Request – Problemas de sintaxe na requisição (JSON inválido, parâmetros faltando).
  • 401 Unauthorized – Requisição não autenticada. Use junto com o cabeçalho WWW-Authenticate.
  • 403 Forbidden – Autenticado, mas sem permissão. Não revele detalhes sobre por que o acesso foi negado.
  • 404 Not Found – Recurso inexistente. Cuidado: não use 404 para esconder recursos que existem mas são privados (melhor usar 403 genérico).
  • 409 Conflict – Conflito de estado (ex.: tentar criar um registro que já existe).
  • 422 Unprocessable Entity – Semântica inválida (ex.: campo de e-mail com formato errado). Prefira 422 em vez de 400 para validações de negócio.

Exemplo prático: Uma API de login deve retornar 401 quando o token está ausente, e 403 quando o token é válido mas o usuário não tem acesso ao recurso. Misturar os dois gera confusão e vazamento de informações.

5xx – Erro do servidor (seja genérico)

  • 500 Internal Server Error – Erro inesperado. Nunca inclua detalhes da exceção no corpo da resposta em produção.
  • 502 Bad Gateway – Quando um servidor intermediário recebe resposta inválida de um upstream.
  • 503 Service Unavailable – Para manutenção ou sobrecarga. Inclua o cabeçalho Retry-After quando possível.
  • 504 Gateway Timeout – Timeout do upstream.

Boa prática: Para todos os 5xx, logue o erro internamente e retorne uma mensagem amigável e genérica. Evite expor stack traces ou informações de infraestrutura.

Segurança e privacidade nos status codes

Os códigos de status podem vazar dados sensíveis se usados de forma descuidada:

  • Evite 404 diferenciado para recursos existentes/inexistentes – Isso permite que invasores descubram endpoints válidos. Um atacante pode mapear sua API testando endpoints: se um 404 indica "recurso não encontrado" e outro 403 indica "recurso existe mas negado", ele já sabe onde atacar. A prática recomendada é retornar 404 para ambos os casos, sem informar se o recurso existe.
  • Não exponha motivos específicos em 401/403 – Mensagens como "senha incorreta" ou "token expirado" ajudam atacantes. Use respostas genéricas: "Credenciais inválidas".
  • Em 500, nunca inclua detalhes de implementação – Stack traces, nomes de arquivos ou números de linha podem revelar vulnerabilidades.

Nossa ferramenta HTTP status codes foi planejada para uso no navegador: toda consulta é local, sem envio de dados para servidores. Assim você pode pesquisar códigos e classes sem preocupações com privacidade.

Erros comuns ao implementar HTTP status codes

  1. Usar 200 para indicar erro – Muitas APIs retornam 200 com um campo error no JSON. Isso quebra contratos e dificulta o tratamento por clientes. Sempre use o código correspondente ao tipo de resposta.
  2. Confundir 401 com 403 – 401 significa "não autenticado"; 403 significa "autenticado, mas sem permissão". Usar 401 para negar acesso por falta de permissão faz o cliente tentar reautenticar sem sucesso.
  3. Redirecionamento com 301 para recursos temporários – Como mencionado, isso causa problemas de SEO e cache indevido.
  4. Ignorar 204 em operações sem corpo – Retornar 200 com corpo vazio em um DELETE consome largura e confunde clientes que esperam dados.
  5. Retornar 500 para erros de validação – Validação é responsabilidade do cliente (4xx). 500 deve indicar algo inesperado no servidor.

Alternativas e ferramentas complementares

Além da nossa ferramenta online, você pode adotar:

  • Middlewares de validação – Frameworks como Express (Node.js), Django (Python) ou Laravel (PHP) possuem middlewares que garantem o status code correto.
  • Interceptors HTTP – Em front-ends, use interceptors (ex.: Axios) para tratar códigos globalmente e exibir mensagens amigáveis.
  • Documentação de API – Especifique claramente quais status codes cada endpoint pode retornar. Ferramentas como Swagger/OpenAPI ajudam.

Também recomendamos consultar a categoria [Web](/), onde você encontra outros recursos sobre protocolos, cabeçalhos e boas práticas de desenvolvimento.

Perguntas frequentes

  1. Qual a diferença entre 401 e 403?

401 Unauthorized significa que a requisição não possui credenciais válidas. 403 Forbidden indica que as credenciais são válidas, mas o acesso ao recurso é negado.

  1. Devo usar 404 ou 403 para recursos privados?

Para evitar vazamento de informação, recomenda-se usar 404 tanto para recursos inexistentes quanto para recursos existentes mas sem permissão, a menos que você queira explicitamente informar que o recurso existe.

  1. Qual código usar para um formulário com dados inválidos?

Use 422 Unprocessable Entity. Esse código indica que a requisição está bem formatada, mas os dados não passaram na validação semântica.

  1. Posso usar 200 para erros de negócio?

Não. Cada tipo de resposta deve ter seu código correspondente (4xx ou 5xx). Isso torna a API previsível e facilita o tratamento por clientes.

  1. A ferramenta HTTP Status Codes armazena minhas consultas?

Não. A ferramenta foi planejada para uso no navegador; todas as consultas são processadas localmente e nenhum dado é enviado a servidores. Sua privacidade está protegida.

Conclusão

Dominar os códigos de status HTTP é uma habilidade fundamental para qualquer desenvolvedor web. Ao seguir as boas práticas descritas, você melhora a comunicação entre front-end e back-end, aumenta a segurança contra vazamento de informações e oferece uma experiência mais consistente para seus usuários. Lembre-se de consultar regularmente a lista completa de códigos em nossa ferramenta HTTP status codes e revisar sua API periodicamente para garantir que cada resposta está usando o código adequado.

Dominar esses códigos não só evita bugs, como também contribui para um ecossistema web mais seguro e previsível. Comece hoje mesmo a aplicar essas práticas no seu projeto.