O que são Códigos de Status HTTP?

Códigos de status HTTP são respostas padronizadas que os servidores web enviam aos clientes para indicar o resultado de uma solicitação. Eles são divididos em cinco categorias, cada uma indicada pelo primeiro dígito do código de três dígitos.

Categorias de Códigos HTTP

Códigos Mais Comuns

Quando Usar Cada Código em APIs REST

Diferenças Importantes

Melhores Práticas para APIs

• Seja consistente: Use os mesmos códigos para situações similares
• Use códigos específicos: Não use apenas 200 e 500 para tudo
• Inclua mensagens: O código sozinho pode não ser claro, adicione mensagem explicativa
• Documente: Especifique quais códigos sua API pode retornar em cada endpoint
• Errors com detalhes: Retorne JSON com erro, mensagem e sugestão de correção
• 4xx vs 5xx: Diferencie claramente erros do cliente dos erros do servidor
• Rate limiting: Use 429 Too Many Requests quando apropriado

Exemplo de Resposta de Erro Bem Estruturada

{
  "status": 400,
  "error": "Bad Request",
  "message": "Email inválido",
  "details": {
    "field": "email",
    "value": "usuario@",
    "issue": "Formato de email inválido"
  },
  "timestamp": "2024-01-17T10:30:00Z",
  "path": "/api/users"
}

Códigos Menos Conhecidos Mas Úteis

Testando Códigos HTTP

# Ver apenas o status code
curl -I -s -o /dev/null -w "%{http_code}" https://exemplo.com

# Ver headers completos
curl -I https://exemplo.com

# Fazer POST e ver resposta
curl -X POST https://api.exemplo.com/users -d '{"name":"João"}' -H "Content-Type: application/json" -v

fetch('https://api.exemplo.com/users')
  .then(response => {
    console.log('Status:', response.status);
    console.log('Status Text:', response.statusText);
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Perguntas Frequentes

Por que recebo 304 em vez de 200?

304 Not Modified significa que o recurso não mudou desde a última requisição. O navegador está usando a versão em cache. Isso é bom para performance! Quer forçar 200? Faça hard refresh (Ctrl+Shift+R) ou desabilite cache nas DevTools.

Posso criar meus próprios códigos HTTP?

Tecnicamente sim, mas NÃO FAÇA ISSO. Use os códigos padronizados. Se nenhum se encaixa perfeitamente, use o mais próximo e adicione detalhes no corpo da resposta. Códigos customizados quebram caches, proxies e frameworks.

O que fazer quando vejo 502/503 constantemente?

502 geralmente indica problema com proxy/load balancer ou servidor backend. 503 indica sobrecarga ou manutenção. Se você é o desenvolvedor, verifique logs do servidor. Se é usuário, aguarde alguns minutos ou contate o suporte.