Códigos de status HTTP

Todos os códigos de status HTTP registrados: o que significam, quando aparecem e onde são definidos.

Select a code

Pick a code from the list to see when it is used, the specification that defines it and a command to try it. Use the arrow keys to move through the list.

64 registered codes · 17 unofficial

/ search↑ ↓ move

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 o que aconteceu com a requisição. O primeiro dígito indica a classe: 1xx é informativo, 2xx significa sucesso, 3xx significa redirecionamento, 4xx significa que a requisição estava errada e 5xx que o servidor falhou.

Os códigos são definidos na RFC 9110, HTTP Semantics, que substituiu a RFC 7231 em 2022, e em algumas outras RFCs, como a RFC 6585 para o 429 Too Many Requests. A IANA mantém o registro oficial. A RFC 9110 renomeou dois códigos: o 413 agora é Content Too Large (antes Payload Too Large) e o 422 é Unprocessable Content (antes Unprocessable Entity). Os números e o comportamento não mudaram.

Alguns códigos que você encontra não estão no registro. O nginx registra 499 quando um cliente fecha a conexão antes de a resposta ficar pronta, o Cloudflare envia de 520 a 526 quando não consegue uma resposta utilizável do servidor de origem, e o Laravel envia 419 quando o token CSRF de um formulário expirou. Eles aparecem separados, marcados como não oficiais.

O código de status é a primeira coisa que um teste de API deve conferir, porque o resto da resposta depende dele. Um 201 Created diz que um POST criou um recurso novo, um 404 que o recurso não existe e um 500 que o servidor falhou, caso em que o body pode ser uma página de erro em vez do JSON que você esperava.

Como usar esta ferramenta

1Navegue pela lista, agrupada de 1xx a 5xx com os códigos não oficiais no final, ou filtre com os botões de classe.
2Busque por número, nome ou sintoma, como 404, 5xx, redirect, timeout ou um nome antigo como Unprocessable Entity. Pressione / para ir à caixa de busca de qualquer ponto da página.
3Selecione um código, ou percorra a lista com as setas do teclado, para ver o que ele significa, quando aparece, a especificação que o define e códigos relacionados para comparar.
4Copie o comando curl em Try it para fazer o endpoint de status do testingapis.com devolver esse código, ou copie um link: /pt-br/tools/http-status/#429 abre o 429 direto.

Solução de problemas

Um 401 mesmo enviando um token: O token está expirado, malformado, foi enviado no header errado ou está sem o prefixo Bearer . O header de resposta WWW-Authenticate costuma dizer qual. Já um 403 significa que o token é válido, mas não tem permissão.
Um 415 para um body JSON: A requisição não tem o header Content-Type: application/json, então o servidor não trata o body como JSON. O -d do curl envia application/x-www-form-urlencoded, a menos que você defina o header.
Um POST vira GET depois de um redirecionamento: Os clientes seguem 301 e 302 repetindo a requisição como GET, sem o body. Servidores que precisam manter o método devem enviar 307 ou 308.
Um 502 ou 504 vindo de um load balancer: O proxy na frente da aplicação não recebeu uma resposta válida: 502 quando a aplicação caiu ou fechou a conexão, 504 quando ela demorou mais que o timeout do proxy. Os logs da própria aplicação mostram a causa.
499 nos logs do nginx: O cliente desistiu antes de a resposta ficar pronta: um usuário saiu da página, ou um cliente ou proxy intermediário estourou o timeout. Requisições lentas ao backend são a causa mais comum.

Perguntas frequentes

Qual a diferença entre 401 e 403?

401 Unauthorized significa que o servidor não sabe quem você é: as credenciais estão faltando, expiradas ou erradas. 403 Forbidden significa que ele sabe quem você é, mas essa identidade não tem permissão para fazer isso. Fazer login de novo pode resolver um 401, não um 403.

Uma API deve devolver 400 ou 422 para entrada inválida?

Os dois são usados. Uma convenção comum é 400 para uma requisição que o servidor nem consegue ler, como JSON malformado, e 422 para dados bem formados que quebram uma regra, como um campo obrigatório faltando ou um email inválido.

Qual a diferença entre 502, 503 e 504?

Os três costumam vir de um proxy ou load balancer na frente da aplicação. 502 Bad Gateway significa que ele recebeu uma resposta inválida do servidor por trás, 503 Service Unavailable que o serviço está sobrecarregado ou em manutenção, e 504 Gateway Timeout que o servidor por trás não respondeu a tempo.

Qual código de redirecionamento devo usar?

301 e 308 são permanentes, 302 e 307 temporários. 307 e 308 exigem que o cliente repita a requisição com o mesmo método e o mesmo body, enquanto os clientes costumam transformar um POST em GET depois de um 301 ou 302. Use 303 See Other para mandar o cliente a uma página de resultado depois de um POST.

418 I'm a teapot é um código de status de verdade?

Ele vem da RFC 2324, uma piada de 1º de abril de 1998 sobre controlar cafeteiras. A RFC 9110 lista o 418 como não usado, mas reservado, porque muito software já o reconhece. Ele não foi feito para erros reais.

Como testo como meu app lida com um código de status específico?

Chame um endpoint que devolve o código que você pedir. GET https://api.testingapis.com/api/status/503 responde com um 503 e os headers que esse status costuma trazer, como Retry-After. Qualquer código de 200 a 599 funciona.