Códigos de status HTTP: semântica e padrões de arquitetura

Códigos de status HTTP são códigos de resposta de três dígitos definidos na RFC 9110 que codificam o resultado do processamento de uma requisição. No nível do protocolo, eles são sinais legíveis por máquina que intermediários e clientes usam para determinar comportamento de cache, elegibilidade para retry e ciclo de vida da conexão sem inspecionar o corpo da resposta.

Como os códigos de status funcionam no nível do protocolo

O papel dos códigos de status na semântica HTTP

Códigos de status ocupam a primeira linha de uma resposta HTTP e não têm opcionalidade — toda resposta deve incluir um. Eles são divididos em cinco classes pelo primeiro dígito, cada uma definindo uma categoria principal de semântica de resposta. Os dois últimos dígitos fornecem granularidade dentro da classe mas não carregam significado estrutural.

HTTP/1.1 200 OK\r\n
          ││ └── Frase de razão (informativa, sem função semântica)
          │└──┴── Código específico dentro da classe
          └── Classe (2 = sucesso)

A frase de razão (“OK”, “Not Found”) não tem função no nível do protocolo. Clientes DEVEM ignorá-la para tomada de decisão. Apenas o código numérico é autoritativo.

Códigos de status e a chave de cache HTTP

Códigos de status determinam o comportamento de cache através do header Cache-Control e da capacidade de cache inerente ao código. RFC 9111 define a seguinte capacidade de cache padrão:

Extensibilidade de códigos de status

RFC 9110 reserva toda a faixa 1xx-5xx mas não restringe o registro de novos códigos dentro dessas classes. O IANA HTTP Status Code Registry gerencia o conjunto oficial. Códigos personalizados seguem regras semânticas:

• Códigos 1xx são informativos (resposta final ainda não disponível)
• Códigos 2xx indicam sucesso
• Códigos 3xx exigem ação do cliente para completar a requisição
• Códigos 4xx indicam erro do cliente
• Códigos 5xx indicam erro do servidor

Códigos de status como sinais de protocolo

Sinais de ciclo de vida da conexão

• 101 Switching Protocols: Atualiza conexão de HTTP para um protocolo diferente (WebSocket, HTTP/2). Após esta resposta, a conexão HTTP é substituída.
• 408 Request Timeout: Servidor fecha conexões ociosas. Cliente deve tentar novamente em uma nova conexão.
• 421 Misdirected Request: Requisição foi enviada a um servidor que não pode responder. Cliente deve tentar em conexão ou host diferente.

Semântica de retry

Clientes NÃO DEVEM tentar automaticamente em 400, 401, 403, 404 ou 405. Estes indicam uma condição do lado do cliente que não mudará com repetição.

Arquitetura avançada de troubleshooting

Rastreando códigos de status através do caminho da requisição

Em sistemas distribuídos, um código de status é modificado em cada camada. Entender qual camada gerou o código é essencial:

Requisição do Cliente
  │
  ▼
Camada Edge/CDN (gera 403 para WAF, 502/504 para problemas de origem)
  │
  ▼
Balanceador de Carga (gera 503 para upstream sem instâncias saudáveis)
  │
  ▼
API Gateway (mapeia erros downstream, gera 502)
  │
  ▼
Aplicação (gera 200/4xx/5xx)
  │
  ▼
Dependências Upstream (geram erros que propagam)

O código de status que o cliente vê é o ÚLTIMO código gerado ao longo deste caminho. Para encontrar a causa raiz, você deve inspecionar logs em cada camada.

Padrões de propagação de erro

Padrões de arquitetura de códigos de status

Esquema uniforme de erro

Respostas de erro devem seguir um esquema consistente para que clientes as interpretem uniformemente:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "id": "req_abc123",
    "detail": "O campo 'email' deve ser um endereço de email válido",
    "source": {
      "pointer": "/data/attributes/email"
    }
  }
}

Este padrão, baseado na RFC 9457 (Problem Details for HTTP APIs), separa o componente legível por máquina (código de status) dos componentes legíveis por humanos e acionáveis por máquina no corpo.

Mapeamento de códigos de status entre protocolos

Mapeamento gRPC para HTTP:

Métricas e Medição

• Error budget de código de status: Taxa máxima de 5xx permitida em uma janela contínua (SLO típico: 99,9% de disponibilidade = 0,1% de budget 5xx)
• Tempo médio para acknowledgment (MTTA): Tempo do alerta 5xx até o acknowledgment do engenheiro (meta: <15 minutos para P1)
• Tempo médio para resolução (MTTR): Tempo do alerta até a normalização da taxa de erro (meta: <60 minutos para P1)

Referências do setor:

• 99,9% de disponibilidade permite 8,76 horas de downtime por ano (Google SRE)
• 99,99% de disponibilidade permite 52,56 minutos de downtime por ano (Google SRE)
• Principais causas de erros 5xx: bugs de deployment (40%), falhas de dependência (30%), mudanças de configuração (20%), exaustão de capacidade (10%) (Catchpoint, 2025)

Erros Comuns e Correções

Erro: Retornar 200 OK para todas as respostas e colocar informações de erro apenas no corpo Correção: Sempre retorne a classe de código de status correta. Proxies, CDNs e ferramentas de monitoramento leem o código de status, não o corpo. Códigos de status incorretos quebram cache, alertas e lógica de retry.

Erro: Usar 403 quando 401 é o correto Correção: 401 indica que o cliente não está autenticado. 403 indica que o cliente está autenticado mas não tem autorização. Usar 403 para ambos impede que clientes saibam se precisam reautenticar ou solicitar permissões diferentes.

Erro: Não implementar o header Retry-After para 429 e 503 Correção: Inclua Retry-After em segundos ou formato de data HTTP. Sem ele, clientes usam atrasos de retry específicos da implementação, frequentemente causando tempestades de retry.

Erro: Armazenar em cache respostas 4xx sem opt-in explícito Correção: Por padrão, CDNs e proxies não devem cachear respostas 4xx. Se o cache for desejado (ex: 410 Gone), defina Cache-Control explicitamente.

Erro: Ignorar a diferença entre 502 e 503 no monitoramento Correção: 502 indica falha de dependência upstream. 503 indica um problema de capacidade ou disponibilidade local. Cada um dispara um caminho de resposta a incidentes diferente.

Casos de uso avançados

Propagação de erro em microsserviços

Em uma arquitetura de microsserviços, um único 500 de um serviço upstream pode causar cascata. Implemente o seguinte padrão:

1. Todos os erros downstream são registrados com correlation IDs
2. O erro upstream é mapeado para um 502 para o cliente
3. Circuit breakers previnem falhas em cascata retornando 503 imediatamente quando limites de erro são excedidos
4. Respostas de fallback (200 com dados obsoletos) são preferidas a 502 para endpoints de leitura quando aceitável

Tratamento de erro em GraphQL

GraphQL desvia do uso padrão de códigos de status HTTP. Uma única consulta pode falhar parcialmente e ter sucesso parcialmente:

{
  "data": {
    "user": null,
    "posts": [...]
  },
  "errors": [
    {
      "message": "Usuário não encontrado",
      "locations": [{"line": 2, "column": 3}],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "status": 404
      }
    }
  ]
}

Endpoints GraphQL tipicamente retornam 200 mesmo quando ocorrem erros, com detalhes no array errors. Algumas implementações retornam 400 para problemas no nível da requisição. Esta é uma escolha de design deliberada que sacrifica a semântica HTTP pela capacidade de resposta parcial.

Entrega de Webhooks

A entrega de webhooks usa códigos de status de forma diferente. O sistema de entrega espera 2xx para confirmar recebimento. Qualquer non-2xx dispara retries com backoff exponencial:

• 200: Entregue com sucesso
• 202: Recebido, processando assincronamente
• 400-499: Má configuração do cliente — webhook pode ser desabilitado após falhas repetidas
• 500-599: Erro do servidor — tentará novamente com backoff

Perguntas Frequentes

Qual é a relação entre códigos de status HTTP e TCP/IP? Códigos de status HTTP são um conceito da camada de aplicação. Eles não têm relação direta com TCP/IP. Uma conexão TCP bem-sucedida não garante uma resposta HTTP bem-sucedida, e um reset TCP não produz um código de status HTTP (o cliente vê código de status 0).

Posso definir códigos de status HTTP personalizados? Sim, qualquer código na faixa 1xx-5xx pode ser usado, mas deve seguir as regras semânticas de sua classe. Códigos personalizados devem ser registrados no IANA para APIs públicas. Para APIs internas, qualquer código dentro da classe correta funciona, mas clientes podem não tratar códigos não padrão corretamente.

Como HTTP/2 e HTTP/3 afetam os códigos de status? HTTP/2 e HTTP/3 carregam os mesmos códigos de status que HTTP/1.1. O código de status permanece o mesmo. A diferença está na semântica da conexão: HTTP/2 multiplexa múltiplos streams sobre uma única conexão, então um 408 em um stream não afeta outros. HTTP/3 usa QUIC, então resets de conexão não exigem renegociação TCP.

Por que minha API GraphQL retorna 200 para consultas com falha? Endpoints GraphQL retornam 200 por convenção porque o transporte HTTP em si foi bem-sucedido. Erros são reportados no array errors do corpo da resposta. Isso permite sucesso parcial: um campo pode falhar enquanto outros retornam dados.

O que acontece se um CDN receber um código de status não padrão? O CDN o trata com base em sua classe. Um 4xx não padrão será tratado como erro do cliente, não cacheado por padrão, e passado ao cliente. Um 2xx não padrão será cacheado de acordo com Cache-Control. O valor específico do código importa menos que a classe para o comportamento do CDN.

Como lidar com códigos de status no padrão BFF (Backend for Frontend)? O BFF deve agregar códigos de status downstream e retornar um único status coerente ao frontend. Mapeie múltiplos erros downstream para o código aplicável mais específico. Sempre registre os códigos downstream originais junto com a resposta do BFF para depuração.

Qual é o código de status correto para limitação de taxa por usuário vs por IP? 429 Too Many Requests é correto para ambos. O corpo da resposta deve diferenciar entre limites de nível de usuário e de IP. Use headers como X-RateLimit-Limit e X-RateLimit-Remaining para informações de escopo.

Como os códigos de status interagem com HTTP pipelining? HTTP pipelining (HTTP/1.1) permite múltiplas requisições sem esperar por respostas. Códigos de status para respostas em pipeline DEVEM ser retornados em ordem. Uma resposta com falha não invalida respostas subsequentes no pipeline. HTTP/2 e HTTP/3 eliminaram a necessidade de pipelining com multiplexação.

Devo retornar 404 ou 403 para recursos não divulgados? Retorne 404. Um 403 confirma que o recurso existe mas o acesso é negado. Um 404 não revela nada sobre a existência do recurso. Para recursos sensíveis à segurança (IDs de usuário, caminhos de arquivo), 404 previne divulgação de informação.

Qual é a abordagem correta para versionamento de códigos de status em APIs? A semântica dos códigos de status não deve mudar entre versões de API. Se uma resposta transiciona de 200 para 201 ou 200 para 202, documente como uma mudança crítica. Códigos de status fazem parte do contrato da API. Use uma nova versão de endpoint se o comportamento do código de status precisar mudar.

Como isso se aplica na prática

O gerenciamento avançado de códigos de status HTTP os trata como sinais de protocolo de primeira classe, não como rótulos de erro. Cada código carrega semântica específica sobre cacheabilidade, segurança de retry e ciclo de vida da conexão que intermediários e clientes dependem.

Organizações que executam microsserviços em escala implementam esquemas de erro padronizados (RFC 9457), circuit breakers com saída de código de status apropriada e propagação de correlation ID através de todas as camadas. Códigos de status se tornam entradas para resposta automatizada a incidentes: um pico de 502 dispara verificações de saúde de dependências, enquanto um pico de 503 dispara auto-scaling de capacidade.

Como implementar na Azion

A Azion fornece controle no nível do protocolo sobre o tratamento de códigos de status através de todo o caminho da requisição:

1. Respostas de Erro Personalizadas: Configure comportamentos de resposta por código de status na borda, incluindo headers personalizados (Retry-After, Cache-Control) e corpo
2. Functions: Intercepte e modifique códigos de status programaticamente usando JavaScript ou Rust na borda antes que cheguem ao cliente
3. Métricas em Tempo Real: Monitore distribuições de código de status por aplicação, nó de borda e origem com granularidade de sub-segundos
4. Data Streaming: Exporte metadados completos de requisições incluindo códigos de status, tempos e status upstream para análises avançadas
5. Cache Inteligente: Configure políticas de cache baseadas em classes de código de status para prevenir cache de respostas de erro

Saiba mais na Documentação da Azion.

Recursos Relacionados

• RFC 9457 — Problem Details for HTTP APIs

Fontes:

• IETF. “HTTP Semantics.” RFC 9110. 2022.
• IETF. “HTTP Caching.” RFC 9111. 2022.
• IETF. “Problem Details for HTTP APIs.” RFC 9457. 2023.
• IANA. “HTTP Status Code Registry.” 2026.
• Google SRE. “Service Level Objectives.” 2023.
• Catchpoint. “Root Cause Analysis of 5xx Errors.” 2025.