O que significam os códigos de status HTTP

Toda vez que seu navegador carrega uma página ou um app chama uma API, o servidor responde com um código de status de três dígitos. Na maior parte do tempo você nunca o vê, mas quando algo quebra — um 404, um 500 — esse número é a primeira pista. Este guia te ensina a ler os códigos de status num relance.

Leia o primeiro dígito

O truque é que o primeiro dígito te diz a categoria, então você entende a intenção de um código que nunca viu:

• 1xx — Informational: recebido, ainda processando (raro no uso diário).
• 2xx — Success: deu certo.
• 3xx — Redirection: o recurso está em outro lugar.
• 4xx — Client error: a requisição estava errada (seu lado).
• 5xx — Server error: a requisição estava boa, o servidor falhou.

Essa divisão 4xx contra 5xx é a distinção mais útil ao depurar: 4xx significa conserte a requisição; 5xx significa que a culpa é do servidor.

Os códigos que você realmente vai encontrar

Sucesso e redirecionamentos

• 200 OK — a resposta padrão de “deu certo”.
• 201 Created — um novo recurso foi criado (após um POST).
• 301 Moved Permanently — esta URL mudou permanentemente; atualize seus links. Importante para SEO.
• 302 Found — um redirecionamento temporário; continue usando a URL original.
• 304 Not Modified — sua cópia em cache ainda é válida, então nada foi reenviado.

Erros do cliente (4xx)

• 400 Bad Request — a requisição estava malformada.
• 401 Unauthorized — você precisa se autenticar (fazer login).
• 403 Forbidden — você está autenticado mas não tem permissão.
• 404 Not Found — o recurso não existe.
• 429 Too Many Requests — você está sendo limitado por taxa; vá mais devagar.

Erros do servidor (5xx)

• 500 Internal Server Error — uma falha genérica do lado do servidor.
• 502 Bad Gateway — um servidor upstream retornou uma resposta ruim.
• 503 Service Unavailable — o servidor está sobrecarregado ou fora para manutenção.
• 504 Gateway Timeout — um servidor upstream não respondeu a tempo.

401 vs. 403: uma confusão comum

Esses dois parecem semelhantes mas diferem numa palavra. 401 Unauthorized na verdade significa “não autenticado” — o servidor não sabe quem você é, então faça login. 403 Forbidden significa que o servidor sabe quem você é e mesmo assim você não tem permissão. Um é sobre identidade, o outro sobre permissão.

A lista completa

Para cada código registrado com seu significado — pesquisável e agrupado por classe — veja nossa referência completa de códigos de status HTTP. Se você está depurando respostas de API, nossos guias sobre JWT e codificação de URL cobrem outras duas coisas com que você vai esbarrar constantemente.