O que são os códigos de erro do cliente?

"Você cometeu um erro"

Imagine que você entra em uma biblioteca e pede um livro que não existe. O bibliotecário não se desculpa: não é culpa da biblioteca. Ele diz: "Nós não temos esse livro." Esse é o espírito de um código de status 4xx.

Quando um servidor responde com um código de status 4xx, ele está dizendo: "Há um problema com A SUA requisição. Eu entendi o que você enviou, mas não posso ou não vou processá-la." O erro está do lado do cliente: URL errada, credenciais faltando, dados inválidos, ou algo mais que o cliente fez errado.

Erros do cliente vs. erros do servidor

Códigos de status HTTP na faixa 4xx significam que o cliente cometeu um erro. Códigos na faixa 5xx significam que o servidor cometeu um erro. Essa distinção importa:

Por que isso importa para desenvolvedores?

• Erros 4xx significam que seu código deve guiar o usuário a corrigir sua requisição (mostrar uma mensagem de "página não encontrada", destacar campos inválidos no formulário, pedir login)
• Erros 5xx significam que seu código tem um bug ou sua infraestrutura tem um problema: o usuário não consegue corrigir

A família 4xx em resumo

A faixa 4xx tem muitos códigos, mas um punhado aparece em quase toda aplicação web:

Vamos focar nos mais importantes ao longo deste curso.

A anatomia de uma resposta 4xx

Uma boa resposta 4xx faz mais do que apenas dizer "erro." Ela diz ao cliente o que deu errado e como corrigir:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "errors": {
    "email": ["is not valid"],
    "password": ["is too short (minimum is 8 characters)"]
  }
}

Compare com uma resposta inútil:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Error

A primeira resposta diz ao cliente o que corrigir. A segunda o deixa adivinhando. Sempre mire na primeira abordagem.

4xx no navegador

Quando um navegador encontra um erro 4xx, o que o usuário vê depende da aplicação:

Sem tratamento personalizado de erros:
O usuário recebe uma página padrão crua: a página de fábrica do framework (o Rails traz public/404.html) ou o "404 Not Found" simples do servidor web. Só quando o corpo vem vazio o navegador mostra a própria página de erro.

Com tratamento personalizado de erros:
A aplicação renderiza uma página de erro amigável com informações úteis, links de navegação e talvez uma barra de busca para ajudar o usuário a encontrar o que procurava.

Aplicações profissionais sempre implementam páginas de erro personalizadas. Uma página 404 bem projetada pode transformar uma experiência frustrante em uma positiva.

Equívocos comuns

"401 significa que o usuário não tem permissão"

Não: 401 significa que o usuário não se identificou (não está logado). Se ele está logado mas não tem permissão, isso é 403 Forbidden. Vamos cobrir essa distinção em detalhes na Aula 3.

"422 e 400 são a mesma coisa"

São relacionados mas diferentes. 400 significa que a requisição é malformada (o servidor nem consegue interpretá-la). 422 significa que a requisição é bem formada mas os dados são inválidos (como enviar um email sem @). Vamos explorar isso na Aula 5.

"404 significa que algo está quebrado"

Não necessariamente. Um 404 significa que o recurso não existe naquela URL. Pode ser um erro de digitação, uma página excluída, ou uma URL que nunca existiu. É o erro mais comum e mais normal da web.

Quando retornar qual código

Escolher o código 4xx correto torna sua API e aplicação mais fáceis de entender e debugar:

flowchart TB
  A{"A requisição é malformada?"} -->|"sim"| A1["400 Bad Request"]
  A -->|"não"| B{"O usuário está autenticado?"}
  B -->|"não"| B1["401 Unauthorized"]
  B -->|"sim"| C{"O usuário tem permissão?"}
  C -->|"não"| C1["403 Forbidden"]
  C -->|"sim"| D{"O recurso existe?"}
  D -->|"não"| D1["404 Not Found"]
  D -->|"sim"| E{"Os dados são válidos?"}
  E -->|"não"| E1["422 Unprocessable Content"]
  E -->|"sim"| F["Processar a requisição (2xx)"]

Essa árvore de decisão vai se tornar natural conforme você constrói mais aplicações.

Resumo