Guia completo de códigos de status HTTP | Causas e soluções para erros comuns

Você está desenvolvendo uma API e recebe 422. De repente, 502 aparece em produção. Se o redirecionamento é 301 ou 302 muda o impacto no SEO. Os códigos de status HTTP são a linguagem comum do desenvolvimento Web e compreendê-los corretamente é o primeiro passo para a solução de problemas.

5 categorias de código de status

Códigos mais encontrados por desenvolvedores

200 OK — Sucesso

A resposta de sucesso mais básica. A API está funcionando conforme esperado.

301 Moved Permanently — Redirecionamento permanente

Use quando a URL mudar permanentemente. <strong>Para SEO, a avaliação da URL antiga é transferida para a nova URL</strong>, sendo essencial para migração de site e implementação de HTTPS. Google trata 301 como 「transferência de sinal」.

<strong>problema comum</strong>: retornar 302 quando a intenção é 301. O <code>Redirect</code> do Apache é 302 por padrão. Especifique <code>Redirect 301</code> explicitamente.

302 Found — Redirecionamento temporário

Redirecionamento temporário. Usado para testes A/B e desvio durante manutenção. A avaliação SEO não é transferida.

304 Not Modified — Cache válido

Retornado quando o navegador envia uma requisição condicional com os cabeçalhos <code>If-Modified-Since</code> ou <code>If-None-Match</code> e o recurso não foi alterado. <strong>O corpo não é enviado</strong>, economizando largura de banda.

400 Bad Request — Requisição inválida

O servidor não consegue analisar a solicitação. Causas: JSON inválido, parâmetro obrigatório ausente, incompatibilidade de Content-Type.

# よくあるミス: Content-Type を指定していない
curl -X POST https://api.example.com/users -d '{"name":"Alice"}'
# → 400 (Content-Type: application/json が必要)

# 正しい
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice"}'

401 Unauthorized — Autenticação necessária

Credenciais ausentes ou inválidas. Token Bearer expirado, chave API incorreta.

403 Forbidden — Acesso recusado

A autenticação passou, mas não há permissão. Por exemplo, quando um usuário comum acessa um endpoint exclusivo do administrador. A diferença com 401 é 「presença de autenticação」 vs 「presença de autorização」.

404 Not Found — Recurso não encontrado

O erro mais famoso. Erros de digitação na URL, página deletada, configuração de roteamento incorreta. Para SEO, em alguns casos é preferível usar <code>410 Gone</code> para indicar 「exclusão intencional」.

413 Payload Too Large — Tamanho excedido

Frequente em uploads de arquivo. Verifique <code>client_max_body_size</code> do Nginx (padrão 1MB), <code>upload_max_filesize</code> do PHP e limites do API Gateway.

422 Unprocessable Entity — Erro de validação

A sintaxe JSON está correta, mas é inválida em termos de lógica de negócios (formato de endereço de e-mail inválido, valor de campo obrigatório vazio, etc.). Os erros de validação da REST API geralmente retornam isso.

429 Too Many Requests — Limitação de taxa

Muitas requisições enviadas em pouco tempo. O número de segundos a esperar é indicado no header <code>Retry-After</code>. Solução: implemente exponential backoff.

500 Internal Server Error — Erro interno do servidor

Exceções não tratadas, referências NULL, erros no arquivo de configuração. <strong>Erros mais perigosos</strong>. Sempre verifique os logs do servidor.

502 Bad Gateway — Anomalia do servidor upstream

O proxy reverso (Nginx) não conseguiu se conectar ao PHP-FPM / Node.js / Python WSGI upstream ou recebeu uma resposta inválida. Verifique a reinicialização do processo upstream, falta de memória ou timeout de conexão socket.

503 Service Unavailable — Serviço temporariamente indisponível

Manutenção ou sobrecarga. Informar ao cliente para aguardar com o cabeçalho <code>Retry-After</code>.

504 Gateway Timeout — Timeout do upstream

O servidor upstream não respondeu no prazo. Consultas DB pesadas, latência de API externa. Verifique <code>proxy_read_timeout</code> do Nginx.

Ferramenta de Busca de Código de Status do DevLab

<a href="/ja/tools/http-status/">Ferramenta de Busca de Código de Status HTTP</a> permite pesquisar instantaneamente por número de código ou palavra-chave (ex: 「redirect」, 「forbidden」, 「timeout」), e você pode verificar o significado, causa e solução de cada código em uma lista. Funciona completamente no navegador, sem necessidade de registro.

Ferramentas relacionadas: <a href="/ja/check/headers/">Validação de cabeçalho HTTP</a>, <a href="/ja/check/redirect-chain/">Rastreamento de cadeia de redirecionamento</a>, <a href="/ja/check/security/">Diagnóstico de segurança</a>.

Resumo

Os códigos de status HTTP são a linguagem comum entre servidor e cliente. Conhecimentos frequentes incluem o impacto SEO de 301 vs 302, a distinção de validação entre 400 vs 422 e o diagnóstico de infraestrutura com códigos 500. Quando tiver dúvidas, primeiro verifique o código de status e aplique as soluções descritas acima.