O que são códigos de status HTTP?

Códigos de status HTTP são números de três dígitos que servidores retornam para indicar o resultado da requisição de um cliente. Eles são definidos na especificação HTTP e agrupados em cinco classes pelo primeiro dígito, cada uma representando um tipo diferente de resposta.

Como funcionam os códigos de status HTTP

Quando um cliente envia uma requisição HTTP a um servidor, o servidor a processa e retorna uma resposta com um código de status e, opcionalmente, um corpo de mensagem. O código de status informa ao cliente se a requisição foi bem-sucedida, falhou ou precisa de ação adicional.

Cliente                       Servidor
  │                              │
  ├────── Requisição HTTP ──────►│
  │                              ├── Processa requisição
  │                              │
  │◄───── Resposta HTTP ─────────┤
  │       200 OK                 │
  │       404 Not Found          │
  │       500 Erro Interno       │

Classes de códigos de status

Códigos de status comuns

Quando usar códigos de status HTTP

Use códigos de status HTTP padrão quando precisar de:

• Indicar sucesso ou falha da requisição claramente
• Permitir tratamento automatizado por clientes e proxies
• Seguir convenções de APIs REST
• Integrar com ferramentas de monitoramento e alertas
• Manter compatibilidade com clientes e bibliotecas HTTP

Quando não usar códigos de status HTTP

Não dependa apenas de códigos de status quando precisar de:

• Transmitir contexto detalhado de erros (use o corpo da resposta)
• Suportar protocolos não HTTP (gRPC, WebSocket)
• Comunicar semântica de erro específica da aplicação sem corpo de resposta

Sinais de que você precisa entender códigos de status HTTP

• Integrações de API retornam erros inesperados
• Painéis de monitoramento mostram picos de 4xx ou 5xx
• Usuários relatam páginas quebradas ou transações com falha
• Depuração de requisições de rede no DevTools do navegador
• Configuração de verificações de integridade em balanceadores de carga

Referência de códigos de status

1xx Informativo:

• 100 Continue: Servidor recebeu cabeçalhos, cliente deve enviar corpo
• 101 Switching Protocols: Atualizando para WebSocket ou outro protocolo

2xx Sucesso:

• 200 OK: Resposta padrão de sucesso
• 201 Created: Novo recurso criado (POST)
• 202 Accepted: Requisição aceita para processamento assíncrono
• 204 No Content: Sucesso sem corpo de resposta
• 206 Partial Content: Requisição de intervalo parcial atendida

3xx Redirecionamento:

• 301 Moved Permanently: Recurso movido, atualize requisições futuras
• 302 Found: Redirecionamento temporário
• 304 Not Modified: Versão em cache ainda é válida
• 307 Temporary Redirect: Mesmo método, redirecionamento temporário
• 308 Permanent Redirect: Mesmo método, redirecionamento permanente

4xx Erro do Cliente:

• 400 Bad Request: Sintaxe ou parâmetros inválidos
• 401 Unauthorized: Credenciais ausentes ou inválidas
• 403 Forbidden: Credenciais válidas mas permissão insuficiente
• 404 Not Found: Recurso não existe nesta URL
• 405 Method Not Allowed: Método HTTP incorreto para este endpoint
• 408 Request Timeout: Cliente não produziu requisição a tempo
• 409 Conflict: Requisição conflita com estado atual
• 410 Gone: Recurso foi permanentemente removido
• 422 Unprocessable Entity: Validação semântica falhou
• 429 Too Many Requests: Limite de taxa excedido

5xx Erro do Servidor:

• 500 Internal Server Error: Falha genérica do servidor
• 501 Not Implemented: Servidor não suporta a funcionalidade solicitada
• 502 Bad Gateway: Servidor upstream retornou resposta inválida
• 503 Service Unavailable: Servidor temporariamente indisponível
• 504 Gateway Timeout: Servidor upstream não respondeu a tempo

Métricas e Medição

• Taxa de 4xx: Percentual de requisições com erro do cliente (meta: <5% do total)
• Taxa de 5xx: Percentual de requisições com erro do servidor (meta: <0,1% do total)
• Tempo até primeiro status: Tempo até o código de status ser retornado (meta: <200ms p95)

Referências do setor:

• Taxa média de 4xx na web: 3-7% de todas as requisições (HTTP Archive, 2025)
• Taxa média de 5xx na web: 0,5-2% de todas as requisições (HTTP Archive, 2025)
• 404 é o código 4xx mais comum, responsável por 80%+ dos erros de cliente (HTTP Archive, 2025)

Erros Comuns e Correções

Erro: Retornar 500 para erros de validação de entrada do cliente Correção: Use 400 Bad Request ou 422 Unprocessable Entity para entrada inválida do cliente

Erro: Usar 200 OK para erros e confiar apenas no corpo da resposta Correção: Sempre use a classe de código de status correta. Códigos de status são legíveis por máquina; corpos de resposta não são.

Erro: Expor stack traces em respostas de erro 500 Correção: Retorne uma mensagem de erro genérica em produção e registre os detalhes no servidor

Erro: Não distinguir entre 401 e 403 Correção: 401 significa “não autenticado.” 403 significa “autenticado mas não autorizado.”

Casos de uso de códigos de status HTTP

Aplicações Web

Navegadores interpretam códigos de status para renderizar páginas de erro, seguir redirecionamentos e armazenar recursos em cache. Um 301 dispara atualização automática de URLs. Um 404 exibe uma página de erro amigável.

APIs REST

APIs usam códigos de status para comunicar sucesso (200, 201), erros do cliente (400, 404) e problemas do servidor (500, 503). Clientes usam o código de status para determinar como tratar a resposta.

CDN e Proxies Reversos

CDNs interpretam códigos 3xx para seguir redirecionamentos, armazenar em cache respostas 200/301 e ignorar cache para 4xx/5xx. Elas geram 502/504 quando a origem está inacessível.

Balanceadores de Carga

Verificações de integridade esperam 200 OK para marcar um servidor como saudável. Qualquer resposta 4xx ou 5xx faz o servidor ser removido da rotação.

Perguntas Frequentes

Qual é a diferença entre 401 e 403? 401 Unauthorized significa que o cliente não forneceu credenciais válidas. 403 Forbidden significa que o cliente está autenticado mas não tem permissão para o recurso.

Quando devo usar 400 vs 422? Use 400 para sintaxe inválida (JSON malformado, campos obrigatórios ausentes). Use 422 quando a sintaxe é válida mas o conteúdo viola regras de negócio.

Como um navegador lida com um redirecionamento 301? O navegador segue automaticamente a nova URL fornecida no cabeçalho Location e atualiza bookmarks e links em cache para o novo endereço.

429 é sempre sobre limitação de taxa? 429 Too Many Requests é especificamente para limitação de taxa. A resposta deve incluir um cabeçalho Retry-After indicando quando o cliente pode tentar novamente.

O que acontece se eu receber um erro 502? O servidor atuando como gateway ou proxy recebeu uma resposta inválida de um servidor upstream. Isso tipicamente indica que o servidor upstream está inativo ou mal configurado.

Um código de status pode ser não padrão? Sim. Códigos de status personalizados podem ser usados, mas devem estar na faixa 1xx-5xx. Clientes podem não tratá-los corretamente a menos que documentados.

Qual é a diferença entre 302 e 307? 302 permite que o navegador mude o método da requisição (ex: POST para GET). 307 preserva o método original e o corpo. Ambos são redirecionamentos temporários.

Por que vejo código de status 0 no DevTools do navegador? O código 0 significa que o navegador nunca recebeu uma resposta. Isso tipicamente indica um erro de rede, falha de CORS ou que a requisição foi cancelada.

Como depurar um erro 500? Verifique logs do servidor em busca de stack traces, revise deployments recentes, examine o payload da requisição para casos extremos e teste o endpoint isoladamente.

O que é uma resposta 304 Not Modified? O servidor informa ao cliente que a versão em cache do recurso ainda é válida. O cliente usa seu cache local em vez de baixar novamente.

Como isso se aplica na prática

Códigos de status HTTP são a linguagem universal da comunicação web. Toda requisição que seu navegador, aplicativo móvel ou cliente de API faz recebe um. Entendê-los significa que você pode diagnosticar problemas sem abrir um único arquivo de log — o código de status sozinho frequentemente revela se o problema está no seu lado (4xx) ou no servidor (5xx).

Equipes configuram alertas de monitoramento em torno de códigos de status: um pico em erros 5xx dispara uma resposta imediata, enquanto taxas elevadas de 4xx podem indicar um bug no cliente ou uma integração mal configurada.

Como implementar na Azion

A Azion permite monitorar, registrar e responder a códigos de status HTTP na borda da rede:

1. Monitore códigos de status: Use o Azion Metrics para acompanhar taxas de 2xx, 4xx e 5xx para todas as aplicações
2. Configure alertas: Defina alertas para limites de taxa 5xx para detectar problemas de origem cedo
3. Páginas de erro personalizadas: Use a configuração de resposta de erro da Azion para retornar conteúdo personalizado para respostas 4xx e 5xx
4. Análise de logs: Exporte logs de requisições com códigos de status para sua plataforma de análise via Azion Data Streaming

Saiba mais na Documentação da Azion.

Fontes:

• IETF. “HTTP Semantics.” RFC 9110. 2022.
• IETF. “HTTP Caching.” RFC 9111. 2022.
• IETF. “HTTP Status Codes.” RFC 9110, Seção 15. 2022.
• HTTP Archive. “Web Almanac: HTTP.” 2025.
• MDN Web Docs. “Códigos de status de resposta HTTP.” 2026.