Esta é uma referência pesquisável de todos os códigos de status de resposta HTTP padrão do registro da IANA, de <code>100 Continue</code> a <code>511 Network Authentication Required</code>. Cada código vem com uma explicação em linguagem simples, orientações sobre quando um servidor ou API deve enviá-lo, os headers de resposta que o acompanham e um link para a RFC que o define. Códigos não oficiais comuns — o <code>499</code> do nginx, o <code>419</code> do Laravel, os <code>520</code>–<code>526</code> da Cloudflare — também estão incluídos e claramente marcados. Pesquise por número, nome ou palavra-chave, como "redirect" ou "rate limit".
Como consultar um código de status
- 1Digite um código (
404), o começo de um (40), uma classe (4xx), um nome (teapot) ou uma palavra-chave (rate limit, cache, Retry-After). - 2Restrinja a lista a uma classe com os filtros 1xx–5xx, ou oculte os códigos não oficiais.
- 3Selecione um código — com o mouse ou as setas do teclado — para ver o significado, quando usar, os headers relacionados e a especificação.
- 4Copie o código ou a linha de status completa, ou compartilhe a URL da página: ela termina em
#404 e abre direto nesse código.
As cinco classes de códigos de status
Clientes que encontram um código que não reconhecem o tratam como o código x00 da sua classe, então um 499 desconhecido é tratado como 400 e um 299 desconhecido como 200. É por isso que um código novo pode ser introduzido sem quebrar softwares antigos.
- 1xx Informativos
- Respostas provisórias enviadas antes da final: 100 Continue, 101 Switching Protocols para WebSockets, 103 Early Hints para pré-carregamento.
- 2xx Sucesso
- A requisição funcionou. 200 OK é o padrão; 201 Created e 204 No Content dizem com mais precisão o que aconteceu.
- 3xx Redirecionamento
- O cliente deve procurar em outro lugar, geralmente na URL do header Location — ou, no caso de 304 Not Modified, usar sua cópia em cache.
- 4xx Erro do cliente
- A requisição estava errada: malformada, sem autenticação, proibida, para algo que não existe ou frequente demais. Repetir sem mudanças não vai ajudar.
- 5xx Erro do servidor
- A requisição pode estar certa, mas o servidor, ou algo atrás dele, falhou. Costumam ser temporários e vale tentar de novo com espera progressiva (back-off).
Como escolher o código certo para uma API
A maioria das APIs precisa de apenas uma dúzia de códigos. Para sucesso: 200 com corpo, 201 com header Location quando algo foi criado, 202 quando o trabalho acontece depois e 204 quando não há nada a retornar. Para erros do cliente: 400 para requisições malformadas, 422 para dados bem formados que falham na validação, 401 quando as credenciais estão ausentes ou inválidas, 403 quando são válidas mas insuficientes, 404 para recursos desconhecidos, 409 para conflitos como um e-mail duplicado e 429 para limite de requisições. Para erros do servidor: 500 para bugs, e 502, 503 e 504 para falhas na infraestrutura intermediária.
Seja qual for o código, retorne um corpo que o explique. A RFC 9457 "Problem Details" (application/problem+json) dá a esse corpo um formato padrão com os campos type, title, status e detail. Nunca retorne 200 com um erro dentro do corpo: caches, monitoramento e lógica de retry leem o código de status, não o seu JSON. Para formatar esse corpo, use o formatador de JSON.
Códigos que costumam ser confundidos
- 401 vs 403
- 401 Unauthorized significa "não sei quem você é": faça login ou envie um token válido. 403 Forbidden significa "sei quem você é, e você não pode fazer isso".
- 301 vs 302 vs 307 vs 308
- 301 e 308 são permanentes e transferem o ranqueamento para a nova URL; 302 e 307 são temporários. 307 e 308 garantem que o método e o corpo sejam mantidos, enquanto os navegadores transformam um POST em GET nos casos 301 e 302.
- 400 vs 422
- 400 é para requisições que o servidor não consegue interpretar; 422 para JSON válido cujo conteúdo quebra as regras, como um campo obrigatório ausente.
- 404 vs 410
- 404 diz que não há nada aqui agora; 410 diz que havia algo e foi removido de propósito, o que faz os buscadores o descartarem mais rápido.
- 502 vs 504
- Ambos vêm de um proxy ou load balancer. 502 significa que o upstream respondeu algo inválido ou fechou a conexão; 504 significa que ele não respondeu a tempo.
- 500 vs 503
- 500 é uma falha inesperada, geralmente um bug. 503 é uma condição conhecida e temporária — manutenção ou sobrecarga — e deve vir com Retry-After.
Códigos de status e SEO
Os buscadores leem os códigos de status com atenção. Use 301 ou 308 quando uma página muda de vez, para que o ranqueamento vá junto; um 302 diz a eles que a URL antiga continua sendo a que deve ser indexada. Sirva um 404 ou 410 real para páginas inexistentes — uma página de "não encontrado" que retorna 200 é um "soft 404" e desperdiça orçamento de rastreamento. Durante a manutenção, retorne 503 com Retry-After para que as páginas não sejam removidas do índice. Defina o que os rastreadores podem visitar com o gerador de robots.txt.
Respostas com 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451 e 501 podem ser armazenadas em cache por navegadores e CDNs mesmo sem headers de validade explícitos, então um 404 ou 301 acidental pode persistir; configure o Cache-Control com cuidado nesses casos.
Códigos não oficiais que você verá nos logs
Alguns códigos não estão no registro da IANA, mas são comuns na prática. O nginx registra 499 quando o cliente desiste antes da resposta e 444 quando fechou uma conexão sem responder. A Cloudflare retorna 520–526 quando não consegue uma resposta válida do servidor de origem: 521 significa que a origem recusou a conexão, 522 que o tempo esgotou, 524 que ela levou mais de 100 segundos para responder e 525/526 que o TLS com a origem falhou. O Laravel envia 419 quando um token CSRF expirou. Esses códigos aparecem marcados como "não oficial" na lista e podem ser ocultados.
- O que é um código de status HTTP?
- Um número de três dígitos no início de toda resposta HTTP que diz ao cliente como foi a requisição. O primeiro dígito indica a classe: 1xx informativo, 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente e 5xx erro do servidor.
- Qual é a diferença entre 401 e 403?
- 401 Unauthorized significa que a requisição não tem credenciais válidas, então fazer login pode resolver. 403 Forbidden significa que o servidor sabe quem você é, mas você não tem permissão, então fazer login de novo não vai ajudar.
- Devo usar 301 ou 302 para um redirecionamento?
- Use 301 (ou 308) quando a mudança for permanente, como uma URL alterada ou uma migração de domínio; os buscadores transferem o ranqueamento da página para o novo endereço. Use 302 (ou 307) quando a URL original for voltar.
- O que significa 429 Too Many Requests?
- O cliente está sendo limitado por excesso de requisições. Espere antes de tentar de novo: o header Retry-After, se presente, diz quantos segundos ou até que horas. Os clientes devem aumentar a espera exponencialmente em vez de repetir imediatamente.
- O que causa um erro 502 Bad Gateway?
- Um proxy, load balancer ou CDN na frente do site recebeu uma resposta inválida do servidor por trás dele — geralmente porque a aplicação travou, reiniciou ou fechou a conexão. A correção é no servidor, a partir dos logs da aplicação upstream.
- O que é o código de status 499?
- Um código específico do nginx, registrado quando o cliente fechou a conexão antes que o nginx pudesse enviar a resposta. O cliente nunca o recebe. Muitos 499 geralmente indicam que o backend está lento demais e os clientes estão desistindo.
- 418 I'm a teapot é um código de status de verdade?
- Ele surgiu como uma piada de 1º de abril na RFC 2324 (1998). Não é para uso real, mas como muitos softwares o implementam, a RFC 9110 reserva o 418 para que ele nunca seja atribuído a outra coisa.
- Quantos códigos de status HTTP existem?
- O registro da IANA define cerca de 63 códigos, incluindo alguns reservados ou obsoletos como 306 e 305. Códigos de 100 a 599 são possíveis, e os clientes tratam qualquer código desconhecido como o código x00 da sua classe.
