Códigos de status HTTP Quando retornar 404 versus 410 versus 301 (e pare de adivinhar)

Você retornou 200 com {"error": "user not found"} no corpo. Seus 301s são na verdade 302s. Recursos excluídos continuam retornando 404 para sempre. Vamos passar pelos códigos de status que os desenvolvedores costumam errar mais comumente e o que retornar em vez disso.

4xx vs 5xx: Não são a mesma caixa

A divisão mais fundamental nos códigos de status HTTP: 4xx é erro do cliente, 5xx é seu erro. Simples em teoria, violado constantemente na prática.

O mais comum: retornar 500 para um erro de validação. Um usuário enviou JSON mal formatado para sua API. Isso é um 400 Requisição Inválida — o payload estava errado. Um 500 informa ao cliente que “a aplicação travou”, o que desencadeia alertas, é registrado como erro do servidor e faz sistemas automatizados tentarem novamente (aumentando ainda mais o problema). Se o cliente enviou dados inválidos, diga isso com um 4xx.

404 vs 410: O Problema do Recurso Excluído

404 Não Encontrado significa: “Não tenho esse recurso agora, mas talvez tente novamente mais tarde.” Os web crawlers — incluindo o Googlebot — tratam 404 como temporário. Eles continuarão verificando indefinidamente.

410 Removido significa: “Esse recurso foi permanentemente excluído. Pare de pedir.” O Googlebot remove URLs 410 do índice mais rápido que as 404s e para de crawlear antes. Isso importa para SEO e para o orçamento de crawlear em sites grandes.

A regra prática: se sua API excluir um registro de forma definitiva e ele nunca voltar, retorne 410 em solicitações subsequentes. A única razão para preferir 404 para um recurso excluído é se ele pode ser restaurado — exclusão suave com janela de recuperação, um post publicado que pode ser republicado, etc. Caso contrário, 410 é mais honesto e os motores de busca o agradecerão.

301 vs 302 (e por que 307/308 existem)

301 Movido Permanentemente: Essa URL foi removida para sempre, use a nova. Navegadores armazenam 301s de forma agressiva. Motores de busca transferem o equilíbrio de links para o destino. Se você estiver consolidando domínios ou movendo permanentemente um site, 301 é o que você deseja.

302 Encontrado: Vá para essa outra URL por enquanto, mas volte para a original mais tarde. Sem cache. Sem transferência de equilíbrio de links. Use para redirecionamentos de login, páginas de manutenção temporárias ou testes A/B.

O modo de falha: usar 302 para movimentos permanentes. Você pensa “a mesma coisa, só diferente”, mas os motores de busca não transferem equilíbrio de links por meio de 302s. Anos de trabalho de SEO permanecem ligados à URL antiga enquanto a nova não é indexada. Se você mover algo permanentemente, use 301.

Em seguida há 307 Redirecionamento Temporário e 308 Redirecionamento Permanente. Essas são versões seguras do método: onde um navegador pode reduzir um POST para GET ao seguir um 301/302, os 307/308 preservam o método original. Se você estiver redirecionando endpoints de API que aceitam corpos POST, os 307 (temporário) ou 308 (permanente) mantêm o método inalterado.

Código	Tipo	Caches?	Preserva o método?	Use para
301	Permanente	Sim	Não (pode ser reduzido para GET)	Mudanças permanentes de site, consolidação de URLs
302	Temporário	Não	Não (pode ser reduzido para GET)	Redirecionamentos de login, indisponibilidade temporária
307	Temporário	Não	Sim	Redirecionamento temporário para endpoints POST de API
308	Permanente	Sim	Sim	Redirecionamento permanente para endpoints POST de API

401 vs 403: Autenticação vs Autorização

O nome é confuso. 401 Não Autorizado na verdade significa não autenticado — você não está logado ou seus credenciais estão ausentes ou inválidas. 403 Proibido significa que você está autenticado, mas não tem permissão para acessar esse recurso.

A diferença prática: um 401 deve solicitar uma tela de login ou atualização de token. Um 403 deve mostrar uma mensagem de acesso negado. Retornar o errado e seu cliente não saberá se deve pedir credenciais ou desistir.

Há também uma dimensão de segurança. Algumas APIs retornam 404 em vez de 403 para recursos que o chamador não pode acessar, para evitar revelar que o recurso existe. Se você retornar 403 para um recurso de outro inquilino, você confirmou que ele existe. Retornar 404 é mais seguro em termos de informação, embora dificulte o diagnóstico para usuários legítimos. Escolha a opção que se alinha com seu modelo de ameaça e aplique de forma consistente.

429: Limitação de taxa, com o cabeçalho que realmente ajuda

Um 429 puro Muitas solicitações é irritante. Um 429 com um Retry-After cabeçalho é realmente útil.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After pode ser um número de segundos ou uma data HTTP. Clientes bem comportados irão reduzir automaticamente. Sem esse cabeçalho, você está retornando um código de erro e esperando que o cliente descubra quando tentar novamente — a maioria simplesmente tentará novamente imediatamente, o que anula o propósito da limitação de taxa.

Não retorne 503 para limitação de taxa. 503 significa “serviço indisponível” — infraestrutura fora do ar, implantação em andamento, circuit breaker aberto. A limitação de taxa é uma decisão de política, não um falha de serviço. O 429 existe exatamente para isso.

O “200 com corpo de erro” é um padrão anti-padrão

Esse padrão continua aparecendo em APIs em produção e precisa parar:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

Isso quebra tudo o que depende das semânticas do HTTP. Ferramentas de monitoramento relatam a requisição como bem-sucedida. Balanceadores de carga a passam. Bibliotecas de cliente não lançam. Logs parecem limpos enquanto os usuários veem erros. A correção é uma linha simples: retorne o código de status correto. 200 significa que funcionou. Se não funcionou, não retorne 200.

A mesma lógica se aplica ao 201 vs 200 para a criação de recursos. Se uma POST para /users criar um novo usuário, retorne 201 Criado com um Location com um cabeçalho apontando para o novo recurso. Retorne 200 e você está descartando informações que seus clientes poderiam usar para evitar uma nova requisição.

Cenário da API → Código de status correto

Aqui está uma tabela de referência para os cenários que aparecem mais comumente no desenvolvimento de APIs REST:

Cenário	Código de status	Notas
Corpo da requisição mal formatado em JSON	400 Requisição Inválida	Inclua uma mensagem apontando para o erro de parse
Campo ausente ou inválido na requisição	422 Entidade Inprocessável	422 é mais preciso que 400 para falhas de validação semântica
Token de autenticação ausente ou expirado	401 Não Autorizado	Incluir WWW-Authenticate cabeçalho
Autenticado, mas sem permissão	403 Proibido	Ou 404 se a ocultação da existência do recurso for uma exigência
Recurso não encontrado, pode retornar	404 Não Encontrado	Para ausência temporária ou recursos desconhecidos
Recurso excluído permanentemente	410 Removido	Os web crawlers pararão de verificar mais cedo
Criou um novo recurso	201 Criado	Adicionar Location: /resources/new-id cabeçalho
DELETE foi bem-sucedido, sem corpo	204 Sem Conteúdo	Não retorne um objeto JSON vazio com 200
Mudança permanente de URL	301 Movido Permanentemente	Os motores de busca transferem o equilíbrio de links
Redirecionamento temporário	302 Encontrado	Sem cache, sem transferência de equilíbrio de links
Limite de taxa excedido	Muitas solicitações	Sempre inclua Retry-After
Exceção inesperada no servidor	500 Erro Interno do Servidor	Não revele rastros de pilha no corpo
Dependência upstream está fora do ar	503 Serviço Indisponível	Adicionar Retry-After se a indisponibilidade for limitada
Redirecionamento de POST, preserva o método	307 ou 308	307 temporário, 3 08 permanente

Quando você está no meio de uma PR e precisa verificar o que um código de status realmente significa, o Ferramenta de Consulta de Códigos de Status HTTP fornece a definição do padrão, casos de uso típicos e qual RFC define o código.

Verificando suas cadeias de redirecionamento

Após uma migração de site ou reestruturação de URL, vale a pena verificar a cadeia completa de redirecionamento — especialmente se você tiver 301s que foram posteriormente atualizados para apontar para outro lugar, criando cadeias de múltiplos saltos que prejudicam o equilíbrio de links. O Verificador de Redirecionamento rastreia a cadeia e mostra cada código de status em sequência, para que você possa confirmar que tudo resolve em um único salto.

Você também pode gostar