Photo por Joanna Kosinska no Unsplash

Por mais de 10 anos, trabalhamos com HTTP e APIs seguindo a arquitetura ReST. A maioria das pessoas pensa que as APIs são apenas interfaces que você pode usar para interagir com algum programa de terceiros e que ReST é sobre verbos HTTP, no entanto, a maior parte da comunicação que usamos atualmente pode estar errada apenas porque estamos usando os status codes HTTP incorretos para expressar nossas respostas. E isso pode mudar a vida quando falamos de aplicativos web modernos.

Isso mesmo! Uma API é muito mais expressiva do que simplesmente escrever GET para buscar dados ou POST para criar dados. Essa é a parte da solicitação. E a resposta?

Neste artigo, exploraremos um pouco mais sobre Status Codes do HTTP, quando usar cada um deles e suas definições! Então, vamos nessa!

Sumário

Sumário
O que são status codes?
Classes e categorias de status codes
Por que eu preciso saber disso?
Escolhendo o status code certo para sua API
Coffee Break!

O que são status codes?

Todos os protocolos que usamos hoje foram definidos e especificados em um documento que chamamos de Request For Comments, ou simplesmente RFC, os Status Codes são definidos junto com o próprio protocolo HTTP dentro da RFC2616, o documento que define o que é HTTP/1.1, mais especificamente, na seção 10. Eles também são definidos na seção 6 da RFC7231 sobre a semântica do HTTP/1.1. Eles são um código numérico que varia de 100 até mais ou menos 500 e visam tornar a resposta HTTP mais significativa para o cliente.

Legal, citamos toda a história da Internet apenas para obter uma definição, certo? Mas o que isso significa? Sempre que clicamos em um botão e enviamos uma solicitação para um aplicativo baseado na arquitetura cliente-servidor, esse aplicativo nos responde com outra resposta HTTP, tanto a solicitação quanto a resposta contém um cabeçalho responsável por fornecer o contexto dessa requisição. Os status codes são exibidos a cada resposta em um cabeçalho chamado Status (criativo né?), e eles estão lá apenas para nos dar uma pista do que aconteceu com a nossa solicitação depois que ela foi processada.

Na maioria das vezes, os usuários comuns não veem esses status codes - a menos que algo dê muito errado - mas para nós, programadores, eles são extremamente valiosos. Por exemplo, toda vez que não conseguimos encontrar um recurso ou uma página da Web, uma página de erro 404 é apresentada, esse 404 é o código de status HTTP para Não encontrado.

Em resumo, eles nos fornecem mais informações sobre o que está acontecendo e o que aconteceu com a solicitação que fizemos, e são muito valiosos para os front-enders que desejam mostrar as mensagens de status corretas com base nas respostas do servidor.

Classes e categorias de status codes

Como mencionamos anteriormente, os Status Codes são numerados de 100 a 500; no entanto, esse intervalo não é totalmente preenchido; por exemplo, não temos um código de status 174, pois essa separação foi feita para dividir códigos em categorias. Essas categorias são definidas em centenas, cada centena do intervalo HTTP representa uma categoria ou classe diferente:

100s: Códigos informativos, apenas para reconhecer que a solicitação foi recebida e está sendo processada;
200s: Códigos de sucesso, retornados quando tudo foi processado ou entendido corretamente, geralmente, isso significa que o cliente não precisa executar mais nenhuma ação;
300s: Códigos de redirecionamento, o que significa que o cliente deve solicitar esse recurso em outro lugar;
400s: Códigos de erro do cliente, quando o cliente faz besteira;
500s: Códigos de erro do servidor, quando o servidor faz besteira;

Por que eu preciso saber disso?

Códigos de status não são importantes apenas para os programadores, pois precisamos saber o que está acontecendo para podermos realizar validações ou mensagens de erro, mas também são importantes para monitorar a integridade do aplicativo, bem como SEO.

No monitoramento, é mais fácil conhecer a integridade de um aplicativo por seu código de status, por exemplo, se seu site está retornando muitos 404s, provavelmente alguém fez alguma coisa errada e esqueceu de colocar alguma página online; no entanto, se seu aplicativo estiver exibindo um 500, provavelmente está offline e ninguém pode usá-lo. Portanto, é muito mais fácil para a equipe de desenvolvimento depurar um aplicativo quando ele exibe as informações corretas.

Por outro lado, fora do ambiente de desenvolvimento, quando falamos sobre SEO, códigos de status são a única maneira de os bots de mecanismos de buscas entenderem o que está acontecendo quando "veem" seu site na Internet. Isso significa que, se você é um robô cego que entende apenas códigos de status, se uma página continua retornando 404, isso significa que essa página não é muito boa, pois não existe, portanto, sua classificação deve ser menor do que outras páginas que retornam um código de status 200 porque essas, de fato, existem.

Não explicarei isso em muitos detalhes aqui, porque nosso foco está nos códigos de status e em seus retornos, mas você pode ler mais sobre isso neste excelente artigo que usei para referência.

Escolhendo o status code certo para sua API

Nesta seção, examinaremos todos os códigos de status definidos e seus significados, mas faremos de forma diferente. Vamos dividir esta seção em três:

Códigos de API mais usados, onde falaremos sobre os códigos que já usamos e como devemos usá-los adequadamente
Códigos não tão frequentemente usados, mas devíamos usar mais
Outros códigos, nos quais terminaremos o guia, explicando os códigos de status menos usados, o que não significa que sejam inúteis - exceto um

Neste artigo, abordaremos apenas a primeira parte, para que não seja uma leitura muito longa para todos! Mas, nos próximos artigos da série, abordaremos as outras duas partes!

E ilustraremos tudo com gatos e cachorros para que possamos nos divertir um pouco enquanto fazemos isso!

Status codes mais usados em APIs

Primeiro de tudo, vamos nos aprofundar nas coisas mais comuns, não haverá muito conteúdo novo aqui, afinal, eles já são mais usados. Então, vamos analisar os mais comuns dos códigos de status por classes:

200x

200 - OK

Eu acredito que este é o código de status mais comum já retornado...

O 200 OK é a resposta padrão para solicitações bem-sucedidas. Geralmente, é isso que estamos esperando ver em qualquer lugar. No entanto, a resposta para esse código deve diferir de um método HTTP para outro, conforme descrito no RFC7231.

Quando usá-lo: Geralmente, há outro Código de Status HTTP que expressaria o que você quer dizer de uma maneira melhor, mas, se você tiver dúvidas sobre qual código HTTP usar e sua resposta for um sucesso, então é 200!

201 - Created

Esse código de status geralmente é usado junto com o método POST, pois descreve um recurso que foi criado no servidor após o êxito da solicitação.

Dê uma olhada na definição

Quando usá-lo: Ao criar coisas. Por exemplo, quando você cria um novo usuário no banco de dados, a resposta deve ser 201 com o documento recém-criado como o corpo.

300x

301 - Moved Permanently

Usado quando o recurso que você procura foi permanentemente movido para outro local. Este código de status geralmente vem junto com outro cabeçalho, informando o local exato para onde o recurso foi movido.

Quando usá-lo: Normalmente usado para redirecionamentos permanentes, por exemplo, um site que possui uma página de índice em http://contoso.com e deve ser redirecionado parahttp://foo.com. Mas o problema é que este código de status deve ser usado apenas com os métodos de solicitação GET ou HEAD, para todos os outros métodos que devemos usar 308

302 - Found

Apesar do texto "Found" não nos dar muita pista do que se trata, o código de status 302 é comumente usado por redirecionamentos temporários, informando que o recurso foi movido, mas foi encontrado em outro URI descrito no cabeçalho Location.

Quando usá-lo: Principalmente no mesmo caso que o 301, mas usado em redirecionamentos temporários em que o recurso será encontrado na URL atual novamente. No entanto, temos uma regra: este código de status deve ser usado apenas com os métodos de solicitação GET ou HEAD, para todos os outros métodos que devemos usar 307

400x

400 - Bad Request

Este código de status é a representação oficial da frase "não sei, não me importo". Como ele diz apenas que o servidor encontrou um erro na solicitação do cliente e não conseguiu processá-la. O maior erro da maioria dos desenvolvedores da Web é retornar esse erro SEMPRE que eles encontram uma request que não entendem. O que reduz a quantidade de informações fornecidas ao cliente e, portanto, a expressividade da API.

Quando usá-lo: Quando você já tentou tudo e ainda não conseguiu encontrar o que havia de errado com a solicitação. Caso contrário, use um código de erro mais significativo.

401 - Unauthorized

O código de status 401 normalmente é confundido com 403, a maior diferença é que, no caso de 401, o cliente ainda não está autenticado, portanto, não pode acessar a página.

Quando usá-lo: Quando um recurso não pode ser acessado devido a problemas de autenticação, normalmente usado em páginas de login quando o usuário tenta efetuar login com um usuário ou senha incorretos.

403 - Forbidden

Diferentemente do 401, o código de status 403 refere-se a um recurso que está fora dos escopos da request por qualquer outro motivo diferente de autorização, por exemplo, limitação de escopo.

Quando usá-lo: Geralmente usado quando temos um limite para o que os usuários podem fazer no aplicativo, por exemplo, se eu não sou o administrador, não devo excluir outros usuários, portanto, se tentar fazê-lo, Receberei um erro 403 - Forbidden. A regra geral é lembrar a seguinte sequência:

Se eu não sei quem está fazendo a solicitação, é 401 - Unauthorized
Se eu sei quem está fazendo a solicitação, mas o usuário não tem permissão para fazer isso, é 403 - Forbidden

404 - Not Found

O código de status 404 é o mais familiar para todos, mesmo para aqueles que não são desenvolvedores. É bem simples, o recurso que você estava procurando não pôde ser encontrado neste site.

Quando usá-lo: Quando você não consegue encontrar uma página ou recurso, um caso de uso não tão conhecido é retornar 404 quando uma consulta do tipo find - como /users/1234, quando buscamos um único usuário por ID - retorna nulo. Essa é uma boa prática porque o usuário estava procurando por um recurso específico e ele não existe. Por outro lado, se você estiver em uma consulta search - como /users, ou seja, uma listagem - onde poderá retornar 0 ou mais resultados, a resposta padrão para "Não há usuários registrados" ou "Lista vazia" seria 200.

405 - Method not allowed

Geralmente, quando não implementamos uma rota, mas ela existe, usamos o código de status 405. Esse código diz que o método que estamos usando é um método conhecido para o servidor - o que significa que ele pode processá-lo - no entanto, esse recurso específico não o aceita.

Quando usá-lo: Vamos explicar através de um exemplo. Se você possui um POST /users e um GET /users, mas não possui um DELETE /users, se eu tentar disparar um DELETE /users, você deve retornar um código de status 405 para mim, esse código de status geralmente vem com outro cabeçalho chamado Allow, declarando quais métodos são permitidos.

429 - Too many requests

O clássico "Você está tentando me derrubar?". O código de status 429 é definido em outra RFC, a RFC-6585, para cabeçalhos HTTP adicionais. Ele afirma que o solicitante enviou muitas solicitações em um determinado período de tempo, é o que chamamos de rate limiting.

Quando usá-lo: Esse deve ser o padrão para todas as APIs existentes no mercado que não desejam ser derrubadas por ataques DDoS, mas, como esse não é o caso hoje, o caso de uso mais comum desse código de status é limitar o número de solicitações que um usuário pode fazer antes de ser bloqueado pelo servidor. A maioria dos gateways de API e APIs expostas para usuários finais o usam, como o Twitter, por exemplo, o que permite cerca de 15 solicitações por minuto.

Além disso, se você quiser fazer rate limiting sozinho, a Azure possui uma ferramenta muito interessante que torna isso possível

500x

500 - Internal Server Error

O clássico "eu fiz besteira". Este código de status é enviado como resposta quando o servidor fez algo errado e não sabe como proceder. Se um usuário estiver vendo isso, seu aplicativo está em mau estado, pois esses códigos de status devem estar visíveis apenas para os desenvolvedores do aplicativo. Front-end deve formatar o erro e mostrar uma mensagem mais amigável.

Quando usá-lo: Quando uma exceção é lançada pelo servidor e não é capturada e você não sabe o que aconteceu, mas sabe que está no servidor. Já vi muitas pessoas usando códigos de status como o 400 para mostrar erros no servidor, isso está errado de várias formas...

502 - Bad Gateway

Este código de status destina-se a servidores com proxy. Ele afirma que o servidor que está atuando como gateway ou proxy não pôde concluir a solicitação ou recebeu uma request inválida do cliente.

Quando usá-lo: O programador nunca deve precisar usá-lo manualmente, a menos que você esteja criando uma API proxy ou um servidor proxy; nesse caso, você precisará retornar esta mensagem em vez de 500 que mencionamos anteriormente.

503 - Service Unavailable

O código 503 é mais um código de informação do que um erro, uma vez que afirma que o servidor que gerencia as solicitações não está disponível devido a uma sobrecarga ou manutenção programada. No caso deste último, o servidor pode opcionalmente enviar um cabeçalho Retry-After com um período de tempo para que o usuário possa tentar novamente.

Quando usá-lo: Como mencionei nos outros erros de 500x, esse código geralmente não é definido pelos programadores, pois está no código do servidor, a menos que você seja o desenvolvedor de um servidor, neste caso, o caso de uso é muito obvio.

504 - Gateway Timeout

Este código é uma variação do código 502, a diferença é que, em vez de não receber uma solicitação correta, o servidor de origem não enviou a solicitação dentro do prazo esperado.

Quando usá-lo: Esse código só deve ser retornado se você estiver codificando um gateway e o servidor proxy não respondeu à sua solicitação.

Coffee Break!

Pare por agora! Tome um café enquanto se prepara para a próxima parte desta série, onde falaremos sobre as APIs que não vemos com muita frequência, mas deveríamos.

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Viu algum erro, tem alguma sugestão ou crítica? Deixe seu comentário aqui! Ou então me mande uma mensagem em minhas redes sociais! Todo feedback é bem vindo :D

Website	GitHub	Facebook	LinkedIn	Twitter

Status HTTP Fantásticos e Onde Habitam #1 - Entendendo os códigos