Referência de Códigos de Status HTTP

Explore códigos de status HTTP com suas descrições.

http-status

Code	Name	Class	Meaning
100	Continue	Informational	The client should continue with its request.
101	Switching Protocols	Informational	The server is switching protocols as requested.
200	OK	Success	The request succeeded.
201	Created	Success	The request succeeded and a new resource was created.
202	Accepted	Success	The request was accepted but not yet processed.
204	No Content	Success	Success, but there is no content to return.
206	Partial Content	Success	The server delivered part of the resource (range request).
301	Moved Permanently	Redirection	The resource has permanently moved to a new URL.
302	Found	Redirection	The resource is temporarily at a different URL.
304	Not Modified	Redirection	The cached version is still valid.
307	Temporary Redirect	Redirection	Temporary redirect that preserves the method.
308	Permanent Redirect	Redirection	Permanent redirect that preserves the method.
400	Bad Request	Client Error	The server could not understand the request.
401	Unauthorized	Client Error	Authentication is required and has failed or not been provided.
403	Forbidden	Client Error	The server understood but refuses to authorize the request.
404	Not Found	Client Error	The requested resource could not be found.
405	Method Not Allowed	Client Error	The HTTP method is not supported for this resource.
408	Request Timeout	Client Error	The server timed out waiting for the request.
409	Conflict	Client Error	The request conflicts with the current state of the resource.
410	Gone	Client Error	The resource is permanently gone.
418	I'm a teapot	Client Error	An April Fools joke from RFC 2324.
422	Unprocessable Entity	Client Error	The request was well-formed but semantically invalid.
429	Too Many Requests	Client Error	The client has sent too many requests (rate limited).
500	Internal Server Error	Server Error	A generic server-side error occurred.
501	Not Implemented	Server Error	The server does not support the requested functionality.
502	Bad Gateway	Server Error	An upstream server returned an invalid response.
503	Service Unavailable	Server Error	The server is temporarily overloaded or down.
504	Gateway Timeout	Server Error	An upstream server did not respond in time.

§01 SOBRE ESTA FERRAMENTA

Visão geral

Um código de status é o resumo em uma palavra que o servidor dá do que aconteceu, e escolher o código errado tem consequências que vão muito além da organização: ele muda se os clientes vão tentar de novo, se os caches vão armazenar a resposta, se os rastreadores vão manter a URL e se um proxy vai processar a requisição outra vez.

Esta é uma referência pesquisável dos códigos que você realmente encontra, com a distinção prática de cada um em vez de uma reescrita da especificação.

Como usar

Digite um número (404) ou parte de um nome (gateway) para filtrar a lista. A correspondência acontece nos dois campos, então too many e 429 encontram a mesma entrada.

As cinco classes

Classe	Significado	O que um cliente deveria fazer
`1xx`	Informativo — a requisição ainda está em andamento	Continuar esperando
`2xx`	Sucesso	Usar a resposta
`3xx`	Redirecionamento — o recurso está em outro lugar, ou não mudou	Seguir, ou usar o cache
`4xx`	Erro do cliente — a própria requisição é o problema	Não repetir sem alterar
`5xx`	Erro do servidor — a requisição pode ter estado correta	Repetir com backoff

A divisão entre 4xx e 5xx é a que mais importa na prática, porque é ela que determina o comportamento de repetição. Um servidor que devolve 500 para uma requisição malformada vai receber essa mesma requisição malformada de novo, e de novo, de todo cliente bem comportado que tenha política de retentativa. Devolver 400 interrompe o laço.

As distinções que vale acertar

200 com um erro no corpo. Comum em APIs e quase sempre errado. Toda camada entre você e o cliente — caches, proxies, monitoramento, lógica de retentativa — lê o código de status, não o seu JSON. Um erro que devolve 200 é invisível para todas elas.

201 versus 200 na criação. O 201 deveria trazer um cabeçalho Location apontando para o novo recurso. É essa parte que os clientes usam; o código sozinho acrescenta pouco.

202 Accepted. A resposta certa para trabalho que você enfileirou em vez de executar. É uma promessa, então precisa dizer ao cliente onde conferir — uma URL de status, ou um id de job.

204 No Content. Sucesso com um corpo intencionalmente vazio, tipicamente em um DELETE ou em um PUT que não devolve nada. Ele não pode ter corpo algum, e não um objeto JSON vazio.

304 Not Modified. A resposta a uma requisição condicional cujo ETag ou Last-Modified ainda corresponde. Ela não carrega corpo, o que é justamente o ponto: o cliente já tem os bytes. Se você nunca devolve 304, cada revalidação transfere o recurso inteiro outra vez.

400 versus 422. 400 para uma requisição que o servidor não conseguiu interpretar — JSON malformado, um parâmetro obrigatório faltando. 422 para uma requisição que foi interpretada sem problemas e falhou na validação. A distinção diz ao cliente se ele deve corrigir a serialização ou os dados.

405 Method Not Allowed. Tem de incluir um cabeçalho Allow listando os métodos que são aceitos. Sem ele, o cliente ouviu um não sem nenhum caminho adiante.

409 Conflict. Para uma requisição que não pode ser aplicada ao estado atual — uma edição sobre uma versão desatualizada, uma duplicata que viola uma restrição de unicidade. Não é um genérico «alguma coisa estava errada».

410 Gone. Um 404 mais forte: isto existiu e não vai voltar. Os rastreadores descartam um 410 mais rápido do que um 404, que é o que você quer para conteúdo removido de propósito.

429 Too Many Requests. Precisa de Retry-After. Sem ele, os clientes adivinham, e adivinham mal — normalmente repetindo imediatamente.

502 versus 503 versus 504. 502 significa que um upstream deu uma resposta inválida. 503 significa que este servidor está indisponível, tipicamente sobrecarregado ou em manutenção. 504 significa que um upstream não respondeu em tempo. Eles apontam para três lugares diferentes, e usá-los de forma intercambiável torna uma indisponibilidade mais difícil de localizar.

Exemplos

Um rastreador insiste em requisitar uma página excluída. Devolva 410 em vez de 404.
Um cliente martelando um endpoint que falha. Verifique se a falha devolve 5xx para o que é, na verdade, uma condição 4xx.
Um envio de formulário perde os dados atrás de um redirecionamento. O redirecionamento provavelmente é 301 ou 302; troque por 308 ou 307.
Um CDN se recusa a cachear uma resposta. 2xx e 3xx são cacheáveis por padrão; a maioria dos 4xx não é, e 5xx nunca deveria ser.
Uma API devolve 200 e os clientes ignoram a falha. Eles não estão ignorando — nada os avisou.

Observações

418 I'm a teapot é real, no sentido de que está registrado e permanentemente reservado. Ele vem de uma RFC de primeiro de abril e está na lista porque as pessoas o procuram.

Códigos fora do registro são legais. Um cliente tem de tratar qualquer código desconhecido pela classe dele, então um 299 personalizado é tratado como sucesso e um 599 personalizado como erro de servidor. Usar um deles raramente compensa a confusão.

A lista aqui cobre os códigos em uso real. O registro completo é mantido pela IANA e inclui códigos para WebDAV e outras extensões que um serviço web típico nunca devolve.

Para ver quais códigos uma URL em produção realmente devolve, incluindo a cadeia de redirecionamento dela, use o verificador de cabeçalhos HTTP.

FAQ

Isto envia algo para algum lugar?

Não. A lista de códigos faz parte da página. Ela funciona offline depois de carregada, e nada do que você digita sai do seu navegador.

Qual é a diferença entre 401 e 403?

401 significa que a requisição não foi autenticada — o servidor não sabe quem você é, e uma credencial válida mudaria a resposta. 403 significa que ele sabe e a resposta continua sendo não. Um 401 tem de incluir um cabeçalho WWW-Authenticate dizendo como se autenticar; um 403 não tem nada a oferecer.

Quando devo usar 404 em vez de 403?

Use 404 quando admitir que o recurso existe já seria em si um vazamento de informação. Devolver 403 para /users/42 conta a um atacante que o usuário 42 existe; 404 não conta. É uma mentira deliberada e é a mentira certa para recursos sensíveis à autorização.

Quais redirecionamentos preservam o método da requisição?

307 e 308. Historicamente os clientes convertiam POST em GET ao seguir 301 e 302, e esse comportamento continua difundido, então use 308 para uma mudança permanente e 307 para uma temporária sempre que um POST possa estar envolvido.

429 é a mesma coisa que 503?

Não. 429 significa que este cliente mandou requisições demais e deveria desacelerar. 503 significa que o servidor como um todo não consegue atender ninguém agora. Os dois deveriam trazer Retry-After, e confundi-los faz o backoff do cliente se comportar de forma errada.