O que significam os erros HTTP 400, 401, 403, 404, 429 e 500

Publicado em 2026-10-21 por frfrand

Guía práctica de códigos de respuesta HTTP para saber qué falla entre navegador, API, autenticación y servidor.

Os códigos de status HTTP indicam como um servidor respondeu a uma solicitação. Um 404 geralmente significa que não encontrou o recurso solicitado; um 500 indica um erro interno ao processá-la. Compreendê-los permite diagnosticar um site sem adivinhar qual componente falhou.

O número importa menos que a família

Os códigos 2xx indicam sucesso. Os 3xx se relacionam com redirecionamentos. Os 4xx sinalizam problemas relacionados à solicitação do cliente, e os 5xx indicam que o servidor não conseguiu atendê-la.

Isso não significa que qualquer 4xx seja culpa de alguém: uma API mal projetada também pode responder com um código incorreto.

400: solicitação incorreta

Um 400 Bad Request aparece quando o servidor não pode ou não quer processar uma solicitação devido a um problema que considera do cliente.

Imagine que você envie um JSON com sintaxe inválida ou parâmetros impossíveis de interpretar. O servidor pode retornar 400, idealmente com uma mensagem que explique qual campo verificar.

Mas não use 400 como resposta genérica para qualquer erro. Distinguir situações ajuda muito quem utiliza sua API.

401 versus 403: uma confusão comum

401 Unauthorized tem um nome histórico um tanto enganoso: geralmente indica que a solicitação não possui credenciais válidas para acessar o recurso.

403 Forbidden indica que o servidor compreendeu a solicitação, mas se recusa a realizá-la. Uma pessoa pode estar identificada corretamente e não ter permissão para consultar uma fatura.

Pense assim: 401 é «preciso de credenciais válidas» e 403 é «você não tem acesso a esta operação». Em ambos os casos há nuances e mecanismos de autenticação particulares.

404: recurso não encontrado

O clássico 404 Not Found não demonstra que todo o servidor esteja fora do ar. Pode faltar uma rota, ter sido excluída uma página ou ter sido usada uma URL incorreta.

Às vezes uma API retorna 404 deliberadamente para não revelar se existe um recurso privado ao qual alguém não tem acesso. Isso pode ser apropriado se estiver contemplado pela política de segurança.

Antes de perseguir um erro de implantação, verifique a URL exata, o método HTTP e as rotas que realmente foram registradas pela aplicação.

429: muitas solicitações

Um 429 Too Many Requests aparece quando um limite de solicitações foi excedido. Pode ser temporário e estar acompanhado de informações sobre quando tentar novamente.

Não significa necessariamente que a web tenha um bug. Pode ser a resposta esperada de um sistema que protege recursos.

Uma integração responsável reduz a frequência, respeita as indicações do servidor e evita tentar centenas de vezes por segundo.

500: o servidor falhou

Um 500 Internal Server Error indica que ocorreu um problema inesperado enquanto o servidor atendia a solicitação.

Pode ser um erro de código, uma dependência incorreta, uma configuração incompleta ou muitas outras causas. O código por si só não diz qual.

Para investigá-lo, é preciso revisar os logs da aplicação e a requisição correspondente. Evite mostrar traces completas com senhas ou variáveis secretas aos visitantes.

E os famosos 502, 503 e 504?

Um 502 Bad Gateway geralmente indica que um proxy ou intermediário recebeu uma resposta inválida de outro servidor. Um 503 Service Unavailable sinaliza indisponibilidade temporária ou sobrecarga. Um 504 Gateway Timeout indica que o intermediário não recebeu a resposta necessária a tempo.

Essas diferenças importam quando você usa Nginx na frente de um backend. Um 502 pode apontar para um processo parado, enquanto um 504 pode aparecer quando o backend demora demais.

Como investigar sem perder tempo

Primeiro reproduza o problema e anote URL, método, código e momento. Depois identifique qual componente gerou a resposta: navegador, proxy, backend ou serviço externo.

Se você usa vários serviços, correlacione registros e requisições. Um erro HTTP é uma pista, não o diagnóstico completo.

Como isso se vê no ArduMaker?

Em uma aplicação implantada em um VPS da ArduMaker, os códigos HTTP podem ajudar você a decidir se deve revisar permissões, rotas, Nginx ou processos do backend. A plataforma facilita operar os serviços, mas interpretar o código continua sendo essencial.

Em resumo: 401 não é 403, e 502 não é 504. Entender essas diferenças evita corrigir a parte errada do sistema.

Fontes: Códigos HTTP na MDN · Semântica HTTP RFC 9110.