04 - 4xx - Erro do Cliente (400, 404)

A família de códigos 4xx (Erro do Cliente) indica que ocorreu um erro causado pelo lado do cliente na requisição HTTP. Padronizada na RFC 7231 (atualizada pela RFC 9110), essa categoria sinaliza problemas como sintaxe malformada, autenticação ausente, autorização negada, recurso inexistente ou excedência de limites. Ao contrário dos códigos 5xx (onde o servidor falha), nos 4xx o problema está na requisição do cliente — corrigir o erro exige que o cliente modifique e reenvie a requisição corretamente.

1. Visão Geral da Família 4xx

Os códigos 4xx cobrem uma ampla gama de cenários de erro do lado do cliente. Compreender cada um é essencial para diagnóstico de APIs e aplicações web modernas.

2. 400 Bad Request — Requisição Malformada

O 400 Bad Request indica que o servidor não pôde processar a requisição devido a sintaxe inválida. É o erro mais genérico da família 4xx quando o problema está na própria estrutura da mensagem enviada.

Causas Comuns

• JSON malformado (vírgulas faltando, aspas incorretas).
• Codificação de caracteres inválida.
• Headers obrigatórios ausentes.
• Parâmetros de query string com caracteres não escapados.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"erro": "JSON inválido", "detalhe": "Token inesperado na linha 1, coluna 12"}

3. 401 Unauthorized — Falta de Autenticação

O 401 Unauthorized é retornado quando o cliente precisa se autenticar para acessar o recurso, mas não forneceu credenciais válidas. Sempre deve acompanhar o cabeçalho WWW-Authenticate indicando o esquema exigido (Basic, Bearer, Digest).

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api.meusite.com"

{"erro": "Token JWT ausente ou expirado"}

Diferença Crítica: 401 vs 403

• 401: "Quem é você?" — falta autenticação (não está logado).
• 403: "Eu sei quem você é, mas você não pode acessar isso" — autenticado, mas sem permissão.

4. 403 Forbidden — Acesso Negado

O 403 Forbidden indica que o servidor entendeu a requisição, mas se recusa a autorizá-la. Diferente do 401, autenticar-se novamente não ajudará — o cliente já está autenticado, mas não tem privilégios suficientes.

Cenários Típicos

• Usuário comum tentando acessar painel administrativo.
• IP bloqueado por firewall (WAF).
• Listagem de diretório proibida no Apache/NGINX.
• Permissões de arquivo (chmod) insuficientes no servidor.

5. 404 Not Found — Recurso Inexistente

O 404 Not Found é o código de erro mais conhecido da Internet. Indica que o servidor não encontrou o recurso solicitado na URI fornecida. Pode significar que o recurso nunca existiu, foi removido, ou a URL foi digitada incorretamente.

Causas Comuns

• URL digitada errada pelo usuário.
• Página removida sem redirecionamento (deveria usar 410 Gone).
• ID inexistente em uma API REST (/api/usuarios/99999).
• Rota não implementada no framework web.

# Verificando se uma URL existe
curl -I https://site.com/pagina-inexistente
# HTTP/1.1 404 Not Found

6. 405 Method Not Allowed — Verbo HTTP Inválido

O 405 Method Not Allowed é retornado quando o servidor reconhece a URI, mas o método HTTP utilizado (GET, POST, PUT, DELETE) não é suportado para aquele recurso. Sempre deve incluir o cabeçalho Allow listando os métodos aceitos.

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

{"erro": "Método DELETE não suportado para /usuarios"}

Exemplo: tentar DELETE /api/usuarios (coleção) em vez de DELETE /api/usuarios/123 (recurso específico).

7. 408 Request Timeout — Tempo Excedido

O 408 Request Timeout indica que o servidor encerrou a conexão porque o cliente não enviou a requisição no tempo esperado. Comum em conexões lentas ou instáveis, e em servidores com timeout agressivo (ex: NGINX com client_body_timeout 12s).

8. 409 Conflict — Conflito de Estado

O 409 Conflict sinaliza que a requisição não pôde ser concluída devido a um conflito com o estado atual do recurso. É o código correto para violações de unicidade (email duplicado em cadastro) ou edição concorrente (optimistic locking).

HTTP/1.1 409 Conflict
{"erro": "Email já cadastrado", "campo": "email"}

9. 410 Gone — Recurso Removido Permanentemente

O 410 Gone é semelhante ao 404, mas com uma diferença semântica crítica: indica que o recurso existia, mas foi permanentemente removido e não voltará. É usado para indicar ao Googlebot e outros crawlers que parem de indexar aquela URL. APIs descontinuadas também usam 410 para indicar endpoints depreciados.

10. 418 I'm a teapot — Easter Egg Histórico

O 418 I'm a teapot é um código definido na RFC 2324 (Hyper Text Coffee Pot Control Protocol, de 1º de abril de 1998). Originalmente uma piada, foi implementado em vários frameworks (Node.js, Express, Go). Embora não seja um código de erro "real", alguns servidores o usam como resposta genérica para requisições suspeitas ou para bloquear bots sem revelar a real infraestrutura.

11. 429 Too Many Requests — Rate Limiting

O 429 Too Many Requests é o código padrão para indicar que o cliente excedeu o limite de requisições permitidas em um período (rate limiting). É essencial para proteção contra abuso, DDoS e scraping. Deve acompanhar os cabeçalhos Retry-After e X-RateLimit-*.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

{"erro": "Limite de 100 req/min excedido. Aguarde 60 segundos."}

12. Diagnóstico e Auditoria de Erros 4xx

Para um administrador de redes, analisar os logs de erro 4xx é fundamental para identificar problemas de UX, bugs em clientes e tentativas de ataque:

# Listando os 10 erros 4xx mais frequentes no NGINX
awk '$9 ~ /^4/ {print $7, $9}' /var/log/nginx/access.log | \
    sort | uniq -c | sort -rn | head -10

# Testando autenticacao com curl
curl -i -H "Authorization: Bearer TOKEN_INVALIDO" https://api.site.com/perfil

# Verificando metodos permitidos em um endpoint
curl -X OPTIONS -i https://api.site.com/usuarios

Métricas Importantes em Monitoramento

• Taxa de 404: Alta taxa indica links quebrados ou rotas inexistentes.
• Taxa de 401: Picos indicam tokens expirados em massa ou ataque de força bruta.
• Taxa de 429: Aumentos indicam clientes desrespeitando limites de API.

13. Conclusão: A Responsabilidade do Cliente

Os códigos 4xx são a forma do servidor dizer "o problema está no seu lado". Cada código comunica um tipo específico de falha, permitindo diagnóstico preciso. Para desenvolvedores de APIs, o uso semântico correto dos códigos 4xx é fundamental: um 401 onde deveria ser 403 confunde o cliente, e um 400 genérico onde deveria ser 422 oculta problemas de validação. Dominar a taxonomia 4xx é o que separa uma API amadora de uma API profissional, clara e fácil de consumir.