Códigos de status HTTP são os números de três dígitos que o servidor devolve no início de toda resposta para resumir o que aconteceu. É com base neles que navegadores, clientes, proxies e CDNs decidem se cacheiam, redirecionam, tentam de novo ou mostram um erro para o usuário.
Todo código de status cai em uma das cinco classes definidas pelo primeiro dígito: 1xx informativo, 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente, 5xx erro do servidor. Sabendo a classe, você já tem uma boa ideia do que significa antes mesmo de procurar o código específico.
A maioria das aplicações usa só um conjunto pequeno (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Entender o que cada um *significa* - e a diferença entre 401 Unauthorized e 403 Forbidden, ou entre 301 Moved Permanently e 302 Found - é o que separa um dev de back-end ou de API mediano de um bom.
O que você vai aprender usando esta referência
O primeiro dígito sempre indica a classe: 1xx informativo, 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente, 5xx erro do servidor.
Códigos de status fazem *parte do contrato* da API - clientes devem fazer branching neles, e não tentar interpretar mensagens de erro no corpo da resposta.
4xx significa que o cliente errou em algo (entrada inválida, falta de autenticação, recurso inexistente). 5xx significa que o servidor falhou, independentemente do que o cliente fez.
Como usar a referência de códigos de status passo a passo
1
Busque por código ou por nome
Digite um número (404, 429) ou uma palavra-chave (auth, redirect, rate limit) e os códigos correspondentes aparecem filtrados em tempo real.
2
Filtre por classe
Use os chips de classe (1xx, 2xx, 3xx, 4xx, 5xx) para reduzir a lista quando estiver explorando, em vez de procurar algo específico.
3
Leia a explicação direta
Cada entrada traz quando o código é enviado, o comportamento típico do cliente e a causa mais comum.
4
Compare códigos parecidos
Use os links de "veja também" entre pares confusos (401 vs 403, 301 vs 302) para escolher o certo na sua API.
Sucesso, mas sem corpo. Comum depois de chamadas DELETE ou PUT que não precisam devolver dados.
Todos os três são códigos de sucesso - o que muda é o que a resposta carrega. 201 deveria incluir um header Location apontando para o novo recurso; 204 é vazio por definição.
Redirecionamento temporário. O navegador volta a checar a URL original a cada requisição; favoritos continuam apontando para a URL antiga.
Use 301 quando o recurso realmente mudou de lugar (rebranding, reestruturação de URLs). Use 302 para redirecionamentos curtos como testes A/B, redirecionamento de login ou páginas de manutenção.
O servidor sabe quem você é, mas você não tem permissão para acessar esse recurso.
Se mandar credenciais diferentes pode resolver, retorne 401. Se nenhuma credencial vai ajudar (o recurso simplesmente está fora do alcance daquele usuário), retorne 403.
Gateway timeout - um proxy chegou até o servidor de origem, mas não recebeu resposta a tempo.
Os quatro são erros do servidor, mas contam histórias bem diferentes para quem está debugando. 500 é problema da sua aplicação; 502 e 504 apontam para o caminho de rede; 503 aponta para falta de capacidade.
Erros comuns com códigos de status HTTP
Retornar 200 OK com {"error": "..."} no corpo. Códigos de status fazem parte do contrato - use o certo (400, 404, 500) para que os clientes possam fazer branching.
Usar 401 para erros de permissão. 401 é para autenticação; negativas de permissão são 403.
Usar 200 para recursos recém-criados em vez de 201 com um header Location.
Perguntas frequentes sobre códigos de status HTTP
O que significa HTTP 404?
404 Not Found significa que o servidor entendeu a requisição, mas o recurso naquela URL não existe. Geralmente o caminho está errado, o recurso foi apagado ou a URL foi digitada incorretamente.
Qual é a diferença entre 401 e 403?
401 Unauthorized significa que você não está autenticado - o servidor não sabe quem você é. 403 Forbidden significa que você está autenticado, mas não tem permissão para o recurso. Mandar credenciais diferentes pode resolver o 401; não vai resolver o 403.
Qual é a diferença entre 301 e 302?
301 Moved Permanently é um redirecionamento permanente - navegadores e buscadores atualizam seus registros. 302 Found é um redirecionamento temporário - os clientes continuam visitando a URL original. Use 301 para mudanças definitivas e 302 para desvios temporários.
O que significa HTTP 500?
500 Internal Server Error é um erro genérico do servidor, normalmente disparado quando uma exceção não tratada estoura. O cliente não fez nada de errado - seu servidor falhou em processar uma requisição válida.
Devo sempre usar um código de status específico?
Sim. Retornar 200 OK em falhas ou 500 para tudo que dá errado torna a API muito mais difícil de usar. Escolha o código mais específico que faça sentido - clientes, proxies, monitores e lógica de retry dependem do código de status para tomar decisões.
O que significa HTTP 429?
429 Too Many Requests é enviado quando o cliente atingiu um limite de taxa (rate limit). A resposta deve incluir um header Retry-After informando quando é seguro tentar de novo.
