Qual é a diferença entre 401 e 403?

401 significa que o cliente não está autenticado, por exemplo porque o token está ausente ou expirou. 403 significa que o cliente está autenticado, mas não tem permissão para fazer isso.

Erros de validação devem retornar 400 ou 422?

Ambos são usados. Uma convenção comum é 400 para requisições que não podem ser interpretadas e 422 para requisições bem-formadas cujos valores não passam na validação.

Quando devo usar 301 e quando 308?

Ambos são redirecionamentos permanentes. Com 301, os navegadores podem transformar um POST em GET; o 308 garante que o método e o corpo sejam mantidos. Para simples mudanças de página, 301 serve.

Qual é a diferença entre 502 e 504?

Ambos vêm de um proxy ou balanceador de carga. 502 significa que o servidor por trás dele retornou uma resposta inválida ou travou; 504 significa que ele não respondeu a tempo.

O que significa o código de status 0?

Não é um status HTTP. Os navegadores informam 0 quando nenhuma resposta chegou ao script: a requisição foi bloqueada por CORS, cancelada, teve um erro de rede ou de DNS, ou foi bloqueada como conteúdo misto. Confira o console do navegador e a aba Network para ver o motivo real.

Tudo bem retornar 404 em vez de 403?

Sim. A RFC 9110 permite que um servidor responda 404 quando não quer revelar que um recurso existe a alguém que talvez não possa vê-lo. O GitHub faz isso com repositórios privados. Use 403 quando o cliente pode saber que o recurso existe, mas não tem permissão para acessá-lo.

Quais códigos de status podem ser cacheados por padrão?

Pela RFC 9110, respostas com 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 e 501 podem ser cacheadas de forma heurística quando nenhum cabeçalho Cache-Control ou Expires diz o contrário. Por isso uma CDN pode continuar servindo um 404 por um tempo. Envie cabeçalhos de cache explícitos para controlar isso.

Códigos de status HTTP

Todos os códigos de status HTTP, com o que significam e quando usar.

Sobre esta ferramenta

Consulte qualquer código de status HTTP pelo número ou pelo nome. Cada um tem uma descrição simples e uma nota sobre quando retorná-lo, o que ajuda ao projetar uma API ou ao analisar uma requisição que falha.

Como usar

Digite um código de status, como 404, ou uma palavra, como redirect ou rate limit.
Filtre por classe: 1xx informativos, 2xx sucesso, 3xx redirecionamentos, 4xx erros do cliente, 5xx erros do servidor.
Leia o que cada código significa e quando retorná-lo.

Perguntas

Qual é a diferença entre 401 e 403?: 401 significa que o cliente não está autenticado, por exemplo porque o token está ausente ou expirou. 403 significa que o cliente está autenticado, mas não tem permissão para fazer isso.
Erros de validação devem retornar 400 ou 422?: Ambos são usados. Uma convenção comum é 400 para requisições que não podem ser interpretadas e 422 para requisições bem-formadas cujos valores não passam na validação.
Quando devo usar 301 e quando 308?: Ambos são redirecionamentos permanentes. Com 301, os navegadores podem transformar um POST em GET; o 308 garante que o método e o corpo sejam mantidos. Para simples mudanças de página, 301 serve.
Qual é a diferença entre 502 e 504?: Ambos vêm de um proxy ou balanceador de carga. 502 significa que o servidor por trás dele retornou uma resposta inválida ou travou; 504 significa que ele não respondeu a tempo.
O que significa o código de status 0?: Não é um status HTTP. Os navegadores informam 0 quando nenhuma resposta chegou ao script: a requisição foi bloqueada por CORS, cancelada, teve um erro de rede ou de DNS, ou foi bloqueada como conteúdo misto. Confira o console do navegador e a aba Network para ver o motivo real.
Tudo bem retornar 404 em vez de 403?: Sim. A RFC 9110 permite que um servidor responda 404 quando não quer revelar que um recurso existe a alguém que talvez não possa vê-lo. O GitHub faz isso com repositórios privados. Use 403 quando o cliente pode saber que o recurso existe, mas não tem permissão para acessá-lo.
Quais códigos de status podem ser cacheados por padrão?: Pela RFC 9110, respostas com 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 e 501 podem ser cacheadas de forma heurística quando nenhum cabeçalho Cache-Control ou Expires diz o contrário. Por isso uma CDN pode continuar servindo um 404 por um tempo. Envie cabeçalhos de cache explícitos para controlar isso.

O que são códigos de status HTTP?

Toda resposta HTTP começa com um código de status de três dígitos que diz ao cliente como foi a requisição. Os códigos e seus significados são definidos na RFC 9110, com alguns acrescentados por outras RFCs, como o 429 Too Many Requests da RFC 6585. O primeiro dígito define a classe: 1xx informativo, 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente e 5xx erro do servidor. Um cliente que não conhece um código o trata como o código x00 da sua classe.

É a classe que a maioria dos softwares leva em conta. Os navegadores seguem redirecionamentos 3xx, a lógica de retry geralmente repete algumas respostas 5xx, mas nunca a maioria das 4xx, e o monitoramento conta 5xx como erros do seu lado. A reason phrase depois do número, como “Not Found”, é só informativa, e o HTTP/2 a elimina por completo. É por isso que escolher o número certo importa mais do que a mensagem que você envia com ele.

Qual código de status HTTP minha API deve retornar?

Comece pelos casos comuns. Retorne 200 para uma leitura ou atualização bem-sucedida com corpo, 201 com um cabeçalho Location quando um POST cria algo, e 204 quando não há nada para devolver, como depois de um DELETE. Use 202 quando o trabalho vai para uma fila e termina depois. Evite retornar 200 com uma mensagem de erro no corpo: clientes, caches e ferramentas de monitoramento confiam primeiro no código de status.

Nos erros, separe a culpa do cliente da sua. Use 400 para entrada malformada, 404 quando o recurso não existe, 409 para conflitos como um endereço de e-mail duplicado e 429 com um cabeçalho Retry-After para rate limits. Reserve os 5xx para falhas do lado do servidor e registre os detalhes em log em vez de retornar stack traces. Um corpo de erro consistente, como o Problem Details da RFC 9457, ajuda os clientes a mostrar mensagens úteis.

Como ver o código de status de uma requisição

No navegador, abra as ferramentas de desenvolvedor, vá para a aba Network e recarregue a página. A coluna Status mostra o código de cada requisição, incluindo chamadas fetch com falha feitas por scripts. Na linha de comando, curl -i imprime a linha de status e os cabeçalhos da resposta antes do corpo, curl -I envia uma requisição HEAD para mostrar só os cabeçalhos, e adicionar -L segue os redirecionamentos para você ver cada salto.

Quando um código surpreender você, descubra quem o enviou. Um 502, 503 ou 504 muitas vezes vem do nginx, de um load balancer ou de uma CDN, e não do seu app, então confira o cabeçalho Server e os logs do proxy. Um 404 em uma rota que você sabe que existe geralmente indica um base path errado ou uma divergência na barra final, enquanto 405 significa que o caminho existe, mas não para aquele método. O Conversor curl ajuda a reconstruir a requisição que falha.

Todos os códigos de status HTTP

Todos os códigos de status com o que significam e quando retorná-los, agrupados por classe.

Informativo (1xx)

Código	Nome	Significado	Quando usar
100	Continue	O servidor recebeu os cabeçalhos da requisição; o cliente deve enviar o corpo.	Enviado automaticamente quando um cliente pede com Expect: 100-continue.
101	Switching Protocols	O servidor está mudando para o protocolo que o cliente pediu.	Atualização de uma conexão para WebSocket.
103	Early Hints	Cabeçalhos preliminares para que o navegador possa começar a pré-carregar.	Envie cabeçalhos Link para CSS e fontes enquanto a página ainda está sendo gerada.

Sucesso (2xx)

Código	Nome	Significado	Quando usar
200	OK	A requisição foi bem-sucedida.	Padrão para um GET bem-sucedido ou um POST que retorna um resultado.
201	Created	Um novo recurso foi criado.	Depois de um POST que cria algo. Inclua um cabeçalho Location apontando para o novo recurso.
202	Accepted	A requisição foi aceita, mas ainda não foi processada.	Tarefas em fila ou em segundo plano. Retorne uma forma de acompanhar o progresso.
204	No Content	Sucesso, sem nada para devolver.	Um DELETE ou PUT que não retorna corpo.
206	Partial Content	Só parte do recurso é retornada.	Ao responder a uma requisição Range, para streaming de vídeo ou downloads retomáveis.

Redirecionamento (3xx)

Código	Nome	Significado	Quando usar
301	Moved Permanently	O recurso tem uma nova URL permanente.	URLs antigas após uma reestruturação do site. Navegadores e mecanismos de busca memorizam o redirecionamento.
302	Found	O recurso está temporariamente em outra URL.	Redirecionamentos temporários. Os clientes podem mudar POST para GET; prefira 303 ou 307 para ser explícito.
303	See Other	Obtenha o resultado em outra URL com GET.	Redirecionamento após o POST de um formulário, para que recarregar a página não o envie de novo.
304	Not Modified	A cópia em cache ainda é válida.	Ao responder a uma requisição condicional com If-None-Match ou If-Modified-Since.
307	Temporary Redirect	Repita a mesma requisição em outra URL.	Redirecionamento temporário que deve manter o método e o corpo.
308	Permanent Redirect	Repita a mesma requisição em uma nova URL permanente.	Como o 301, mas o método e o corpo não podem mudar.

Erro do cliente (4xx)

Código	Nome	Significado	Quando usar
400	Bad Request	A requisição está malformada ou é inválida.	JSON que não pode ser interpretado, campos obrigatórios ausentes, tipos errados.
401	Unauthorized	A autenticação está ausente ou é inválida.	Nenhum token, ou um token expirado. Apesar do nome, significa “não autenticado”.
402	Payment Required	Reservado; usado por algumas APIs para problemas de cobrança.	Limite do plano atingido ou falha no pagamento.
403	Forbidden	O cliente é conhecido, mas não tem permissão para fazer isso.	Autenticado, mas sem permissão.
404	Not Found	Não existe nada nesta URL.	Rotas ou IDs desconhecidos. Também usado para esconder recursos que o cliente talvez não deva conhecer.
405	Method Not Allowed	Esta URL não suporta esse método HTTP.	Um POST em um endpoint somente leitura. Inclua um cabeçalho Allow.
406	Not Acceptable	Nenhuma representação corresponde ao cabeçalho Accept.	O cliente pediu XML a uma API que só fala JSON.
408	Request Timeout	O cliente demorou demais para enviar a requisição.	Conexões ociosas. Os clientes podem tentar de novo com segurança.
409	Conflict	A requisição conflita com o estado atual.	Valores únicos duplicados ou uma edição baseada em uma versão desatualizada.
410	Gone	O recurso existiu, mas foi removido para sempre.	Conteúdo excluído ou versões de API desativadas. Mais forte que 404.
411	Length Required	É necessário um cabeçalho Content-Length.	Uploads sem tamanho declarado.
412	Precondition Failed	Um cabeçalho condicional não correspondeu.	If-Match com um ETag desatualizado, para evitar perda de atualizações.
413	Content Too Large	O corpo da requisição é maior do que o servidor aceita.	Uploads acima do limite de tamanho.
414	URI Too Long	A URL é mais longa do que o servidor aceita.	Query strings enormes. Mova os dados para o corpo de um POST.
415	Unsupported Media Type	O formato do corpo não é suportado.	Envio de dados de formulário para um endpoint JSON, ou um Content-Type errado.
416	Range Not Satisfiable	A faixa de bytes pedida está fora do arquivo.	Uma requisição Range além do fim do recurso.
418	I’m a teapot	Uma piada de 1º de abril de 1998 que pegou.	Só para easter eggs.
422	Unprocessable Content	A requisição está bem-formada, mas não passa na validação.	JSON válido com valores inválidos, como uma data de término anterior à data de início.
423	Locked	O recurso está bloqueado.	WebDAV, ou um registro que está sendo editado por outra pessoa.
425	Too Early	O servidor não vai arriscar processar uma requisição que pode ser repetida.	Dados antecipados do TLS (0-RTT).
426	Upgrade Required	O cliente precisa mudar para outro protocolo.	Para forçar uma versão mais nova de TLS ou HTTP.
428	Precondition Required	A requisição precisa ser condicional.	Exigir If-Match em atualizações para evitar perda de gravações.
429	Too Many Requests	O cliente está enviando requisições rápido demais.	Limitação de taxa. Inclua um cabeçalho Retry-After.
431	Request Header Fields Too Large	Os cabeçalhos são grandes demais.	Cookies grandes demais costumam ser os culpados.
451	Unavailable For Legal Reasons	Bloqueado por motivos legais.	Conteúdo removido por ordem judicial ou bloqueado em um país.

Erro do servidor (5xx)

Código	Nome	Significado	Quando usar
500	Internal Server Error	Algo deu errado no servidor.	Exceções não tratadas. Registre os detalhes no log, não os exponha ao cliente.
501	Not Implemented	O servidor não oferece suporte a essa funcionalidade.	Um método HTTP que o servidor não reconhece de forma alguma.
502	Bad Gateway	Um proxy recebeu uma resposta inválida do servidor por trás dele.	O app por trás do nginx ou de um balanceador de carga travou ou retornou lixo.
503	Service Unavailable	O servidor não consegue atender requisições no momento.	Manutenção ou sobrecarga. Inclua Retry-After se você souber quando volta.
504	Gateway Timeout	Um proxy não recebeu resposta a tempo.	O app upstream está lento demais ou travado.
505	HTTP Version Not Supported	A versão do HTTP não é suportada.	Raro; versões de protocolo muito antigas ou muito novas.
507	Insufficient Storage	O servidor não tem espaço para armazenar o resultado.	Disco cheio ou cota de armazenamento atingida.
508	Loop Detected	O servidor encontrou um loop infinito durante o processamento.	WebDAV, ou um ciclo de redirecionamento ou de proxy.
511	Network Authentication Required	O cliente precisa fazer login para ter acesso à rede.	Portais cativos em Wi-Fi de hotéis e aeroportos.

Algo não está funcionando ou um resultado parece errado? Relatar um problema com esta ferramenta