Códigos de Status HTTP Explicados | Guia de Troubleshooting para Desenvolvedores

Códigos de status HTTP são números de três dígitos retornados por servidores em resposta a requisições de clientes. Eles indicam se uma requisição foi bem-sucedida, falhou devido a erro do cliente, falhou devido a erro do servidor, ou requer ação adicional como um redirecionamento. Toda resposta HTTP inclui exatamente um código de status, tornando-os a primeira informação que um cliente ou intermediário usa para determinar o que fazer a seguir.

Como Funcionam os Códigos de Status HTTP

As Cinco Classes de Códigos de Status

Códigos de status são agrupados em cinco classes pelo seu primeiro dígito:

A frase de motivo após o código (“OK”, “Not Found”) é apenas informativa. Clientes devem usar o código numérico para tomada de decisão (RFC 9110).

Códigos de Status e Cache

Nem todos os códigos de status devem ser cacheados. A RFC 9111 define a cacheabilidade padrão:

Códigos de Status e Comportamento de Retry

Clientes e proxies usam códigos de status para decidir se devem tentar novamente:

Códigos de Sucesso 2xx Comuns

200 OK

A requisição foi bem-sucedida. O significado depende do método:

• GET: Recurso retornado no corpo da resposta
• POST: Recurso criado ou ação completada
• PUT: Recurso atualizado
• DELETE: Recurso deletado

201 Created

Um novo recurso foi criado. Usado principalmente com requisições POST. A resposta deve incluir um header Location apontando para o novo recurso.

204 No Content

A requisição foi bem-sucedida mas não há conteúdo para retornar. Comum para requisições DELETE ou atualizações PUT onde o cliente já tem os dados.

206 Partial Content

O servidor está entregando parte de um recurso. Usado com requisições de intervalo para arquivos grandes ou streaming de vídeo.

Códigos de Redirecionamento 3xx Comuns

301 Moved Permanently

O recurso foi movido permanentemente para uma nova URL. Clientes e motores de busca devem atualizar seus registros. O header Location contém a nova URL.

302 Found (Redirecionamento Temporário)

O recurso está temporariamente em uma URL diferente. Requisições futuras devem continuar usando a URL original.

304 Not Modified

O recurso não mudou desde a última requisição do cliente. Usado com headers condicionais como If-None-Match ou If-Modified-Since. Economiza banda ao não reenviar conteúdo inalterado.

307 Temporary Redirect / 308 Permanent Redirect

Como 302 e 301, mas preservam o método HTTP. Use 307/308 em vez de 302/301 para requisições POST ou PUT para evitar converter o método para GET.

Códigos de Erro do Cliente 4xx Comuns

400 Bad Request

O servidor não pode processar a requisição devido a erro do cliente. Causas comuns:

• JSON ou XML malformado no corpo da requisição
• Parâmetros obrigatórios ausentes
• Valores de parâmetros inválidos
• Erros de sintaxe na requisição

401 Unauthorized

Autenticação é necessária. O cliente deve se autenticar antes de acessar o recurso. A resposta deve incluir um header WWW-Authenticate indicando como autenticar.

403 Forbidden

O cliente está autenticado mas não tem permissão para acessar o recurso. Diferente de 401, reautenticar não ajuda—o cliente simplesmente não tem permissão.

404 Not Found

O recurso solicitado não existe. Pode também ser retornado em vez de 403 por segurança (para evitar confirmar que o recurso existe).

405 Method Not Allowed

O método da requisição não é suportado para este recurso. A resposta deve incluir um header Allow listando os métodos válidos.

408 Request Timeout

O servidor fechou uma conexão ociosa. O cliente deve tentar novamente em uma nova conexão.

429 Too Many Requests

O cliente excedeu os limites de taxa. Verifique o header Retry-After para quando tentar novamente.

413 Content Too Large

O corpo da requisição excede o limite configurado do servidor. O cliente deve reduzir o tamanho do payload ou usar upload fragmentado.

Códigos de Erro do Servidor 5xx Comuns

500 Internal Server Error

Um erro inesperado ocorreu no servidor. Este é um código genérico para exceções não tratadas e erros de configuração. O cliente não pode corrigir este problema.

502 Bad Gateway

Um proxy ou gateway recebeu uma resposta inválida de um servidor upstream. Comum em arquiteturas distribuídas com load balancers, CDNs ou API gateways.

503 Service Unavailable

O servidor está temporariamente incapaz de processar requisições. Causas comuns:

• Servidor sobrecarregado
• Manutenção em andamento
• Esgotamento de recursos (memória, conexões, threads)

A resposta deve incluir um header Retry-After.

504 Gateway Timeout

Um proxy ou gateway não recebeu resposta de um servidor upstream dentro do período de timeout. Diferente de 502 (resposta inválida), 504 significa que nenhuma resposta chegou.

Troubleshooting de Erros HTTP

Identifique Onde o Erro Originou-se

Em sistemas distribuídos, erros podem ocorrer em múltiplas camadas:

Cliente → CDN/Edge → Load Balancer → API Gateway → Aplicação → Banco de Dados
          ↑           ↑               ↑              ↑            ↑
       403/502    502/503         502/504       4xx/5xx      502/504

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

Verifique Headers para Pistas

• Server: Identifica qual software gerou a resposta
• X-Cache-Status: Status de cache hit/miss do CDN
• X-Request-ID: ID de correlação para rastreamento entre serviços
• Retry-After: Quando tentar novamente (429, 503)
• WWW-Authenticate: Requisitos de autenticação (401)

Distinga 4xx de 5xx

Quando Usar Cada Código de Status em Sua API

Operações Bem-sucedidas

• 200 OK: Sucesso padrão para GET, PATCH
• 201 Created: Recurso criado via POST
• 202 Accepted: Requisição aceita para processamento assíncrono
• 204 No Content: Sucesso sem corpo (DELETE, alguns PUT)

Erros do Cliente

• 400 Bad Request: Entrada inválida, sintaxe malformada
• 401 Unauthorized: Autenticação ausente ou inválida
• 403 Forbidden: Autenticado mas não autorizado
• 404 Not Found: Recurso não existe
• 409 Conflict: Conflito de estado (duplicata, versão incompatível)
• 422 Unprocessable Entity: Sintaxe válida mas erros semânticos
• 429 Too Many Requests: Limite de taxa excedido

Erros do Servidor

• 500 Internal Server Error: Falha inesperada do servidor
• 502 Bad Gateway: Upstream retornou resposta inválida
• 503 Service Unavailable: Sobrecarga temporária ou manutenção
• 504 Gateway Timeout: Upstream não respondeu a tempo

Métricas e Medição

Acompanhe estas métricas para monitorar padrões de erro HTTP:

• Taxa de erro 5xx: Meta < 0,1% para serviços em produção
• Taxa de erro 4xx: Monitore picos indicando clientes com problemas
• Distribuição de códigos de status: Mudanças repentinas indicam problemas
• Orçamento de erro: Porcentagem de requisições falhadas permitida por SLO

Referências do mercado:

• 99,9% disponibilidade = 8,76 horas de downtime/ano
• 99,99% disponibilidade = 52,56 minutos de downtime/ano
• Principais causas de 5xx: bugs de deploy (40%), falhas de dependência (30%), mudanças de config (20%), capacidade (10%) (Google SRE)

Erros Comuns e Correções

Erro: Retornar 200 OK para erros e colocar detalhes do erro no corpo
Correção: Sempre retorne o código de status correto. Intermediários, monitoramento e clientes dependem do código numérico.

Erro: Usar 403 quando o usuário precisa se autenticar
Correção: Retorne 401 para autenticação ausente, 403 para permissões insuficientes.

Erro: Retornar 500 para erros de validação
Correção: Use 400 ou 422 para falhas de validação do lado do cliente.

Erro: Não incluir Retry-After para 429 e 503
Correção: Sempre inclua orientação de retry para prevenir tempestades de retry.

Perguntas Frequentes

Qual a diferença entre 401 e 403? 401 significa “você precisa se autenticar”. 403 significa “você está autenticado mas não tem permissão”.

Devo retornar 404 ou 403 para recursos que o usuário não pode acessar? Retorne 404 se quiser esconder a existência do recurso. Retorne 403 se o usuário deve saber que existe mas não pode acessá-lo.

Posso criar códigos de status customizados? Sim, mas devem seguir a semântica da classe (2xx para sucesso, 4xx para erros do cliente, 5xx para erros do servidor). Registre códigos customizados com IANA para APIs públicas.

Como CDNs lidam com códigos de status? CDNs fazem cache baseado no código de status e Cache-Control. A maioria das respostas 4xx e 5xx não são cacheadas por padrão.

Qual código de status webhooks devem retornar? Retorne 200 OK para confirmar recebimento. Retorne 202 Accepted para processamento assíncrono. Qualquer não-2xx acionará retries do sistema enviador.

HTTP/2 e HTTP/3 mudam códigos de status? Não. Códigos de status permanecem os mesmos entre versões HTTP.

Minha API deve retornar 500 para erros de lógica de negócio? Não. Use códigos 4xx para condições de erro esperadas. Reserve 500 para falhas técnicas inesperadas.

Qual o código correto para rate limiting? 429 Too Many Requests, com header Retry-After.