Status codes HTTP: escolhendo o retorno certo da sua API

Toda resposta HTTP começa com um número. Antes do JSON, antes de qualquer campo, a API já disse alguma coisa — e quem consome precisa decidir o que fazer com base nisso: mostrar o dado, pedir login, corrigir o formulário ou tentar de novo daqui a pouco.

É por isso que o status code não é um detalhe cosmético. Ele é a primeira instrução que o cliente recebe. Devolver o código errado não deixa a resposta feia: faz o cliente tomar a decisão errada.

🧭 O primeiro dígito aponta a origem

Antes de decorar códigos, vale internalizar a lógica das faixas. O primeiro dígito responde a uma pergunta só: de onde veio o problema?

Essa distinção entre 4xx e 5xx é a mais importante de todas, e é onde mora o erro mais comum em APIs jovens. Um exemplo clássico em Spring Data:

// busca um aluno por id
return repository.findById(id).get();

Se o id não existir, o Optional.get() lança NoSuchElementException, e sem tratamento o Spring converte isso em 500. Ou seja: a API responde "eu falhei, tente de novo" quando a informação correta seria "esse recurso não existe, pare de tentar".

A diferença é prática. Um cliente bem escrito faz retry automático em 5xx e não faz em 4xx. Com o código errado, ele vai insistir indefinidamente em uma busca que nunca vai dar certo.

✅ A faixa 2xx: nem todo sucesso é 200

É tentador responder 200 OK para tudo que deu certo. Funciona, mas joga fora informação que o cliente poderia usar.

O 201 com Location economiza uma requisição inteira: em vez de o cliente vasculhar o JSON atrás do id gerado para montar a próxima URL, ele já recebe o endereço pronto no header.

POST /alunos            →  201 Created
                           Location: /alunos/42

DELETE /alunos/42       →  204 No Content   (corpo vazio)

Um DELETE que devolve 200 com corpo vazio comunica a mesma coisa, mas o 204 diz explicitamente que a ausência de corpo é intencional — e não uma resposta que veio truncada.

↪️ 301 e 302: uma delas é quase definitiva

Os dois redirecionam, mas com consequências bem diferentes:

• 301 Moved Permanently — o navegador guarda esse redirecionamento em cache, e de forma agressiva. Nas próximas visitas ele nem consulta o servidor: vai direto ao novo endereço.
• 302 Found — redirecionamento temporário. O cliente continua perguntando ao servidor a cada requisição.

Vale citar ainda o 304 Not Modified, que não é bem um redirecionamento: é a resposta a uma requisição condicional dizendo "o que você já tem em cache continua válido, pode usar".

🔐 401 e 403: o par mais trocado

Esses dois se confundem por um motivo justo — o 401 se chama Unauthorized, mas trata de autenticação, não de autorização. A distinção correta é:

A regra prática: se refazer o login resolveria, é 401. Se nem o login resolve, é 403.

Há ainda uma consideração de segurança. Responder 403 confirma que o recurso existe — você só não tem acesso. Em endpoints sensíveis, isso vira uma forma de enumerar dados: basta variar o id e observar quem responde 403 e quem responde 404. Por isso, em certos casos, devolver 404 mesmo para algo que existe é a escolha mais defensiva.

🚫 400, 404, 422 e companhia

Dentro da faixa 4xx, a diferença está em qual camada rejeitou a requisição:

A fronteira entre 400 e 422 é a que mais gera debate. Um critério simples que funciona bem: se o erro foi detectado ao ler a requisição, é 400; se foi detectado ao interpretá-la, com todos os campos já válidos, é 422.

💥 500, 502, 503 e 504: onde exatamente quebrou

Essa faixa tem um valor de diagnóstico que costuma passar despercebido: ela indica em que ponto da infraestrutura a coisa falhou.

Na prática isso corta caminho na investigação: um 500 manda você direto para os logs da aplicação. Já 502 e 504 geralmente significam que a aplicação nem chegou a responder — vale olhar antes se o processo subiu, se a porta está certa e quanto tempo a requisição está levando.

🫖 418 e 451: os dois com história

418 I'm a teapot nasceu na RFC 2324, o Hyper Text Coffee Pot Control Protocol, publicada em 1º de abril de 1998 como piada. O código indica que o aparelho é um bule de chá e, portanto, não pode preparar café. Nunca entrou no padrão sério de HTTP — mas sobreviveu, e alguns serviços passaram a usá-lo como resposta discreta para tráfego automatizado detectado.

451 Unavailable For Legal Reasons, por outro lado, é oficial: está na RFC 7725 e sinaliza conteúdo bloqueado por ordem judicial ou exigência legal. O número é uma referência a Fahrenheit 451, o romance de Ray Bradbury sobre queima de livros. A diferença em relação a um 403 genérico é a transparência — o 451 deixa explícito que existe censura, em vez de fingir que a página sumiu.

⚙️ Devolvendo o código certo no Spring Boot

Saber o código correto resolve metade; a outra metade é fazer o framework devolvê-lo. O Spring oferece alguns caminhos, do mais pontual ao mais estruturado.

1. ResponseEntity — controle total

@PostMapping("/alunos")
public ResponseEntity<Aluno> criar(@RequestBody @Valid AlunoForm form) {
    Aluno aluno = service.criar(form);
    URI local = URI.create("/alunos/" + aluno.getId());
    return ResponseEntity.created(local).body(aluno);   // 201 + Location
}

2. @ResponseStatus — quando o código é fixo

@DeleteMapping("/alunos/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)   // 204
public void deletar(@PathVariable Long id) {
    service.deletar(id);
}

3. ResponseStatusException — no fluxo do serviço

return repository.findById(id)
        .orElseThrow(() -> new ResponseStatusException(
                HttpStatus.NOT_FOUND, "Aluno " + id + " não encontrado"));

Trocar .get() por .orElseThrow() é a menor mudança possível para converter aquele 500 do começo do artigo em um 404 honesto.

4. @ControllerAdvice + ProblemDetail

Para padronizar o formato de erro em toda a API, o Spring 6 traz o ProblemDetail, que implementa a RFC 7807 — o mesmo application/problem+json que uso no Budgeting:

@RestControllerAdvice
public class TratadorDeErros {

    @ExceptionHandler(RegraDeNegocioException.class)
    public ProblemDetail regraViolada(RegraDeNegocioException e) {
        ProblemDetail p = ProblemDetail.forStatusAndDetail(
                HttpStatus.UNPROCESSABLE_ENTITY, e.getMessage());   // 422
        p.setTitle("Regra de negócio violada");
        return p;
    }
}

A vantagem é que o cliente passa a receber sempre a mesma estrutura de erro, com status, title, detail e instance — em vez de um formato diferente para cada exceção. Percorro esse retorno na prática, campo por campo, no artigo sobre Swagger UI.

📊 Duas convenções, lado a lado

Convenções diferentes servem a momentos diferentes. Comparando dois projetos meus:

A da esquerda é a da Academia Digital, e aparece em detalhe no artigo sobre o Postman. Ela é mais simples de escrever e suficiente quando o cliente é você mesmo. A da direita é a do Budgeting: exige mais código, e entrega em troca um contrato que qualquer cliente consegue seguir sem ler documentação.

A única linha em que não há troca a ponderar é a do id inexistente. Ali o 500 não é uma escolha de estilo: é uma informação incorreta sobre o que aconteceu.

🗂️ Referência rápida

✅ Conclusão

Não é preciso cobrir a lista inteira para ter uma API bem-comportada. Com meia dúzia de códigos usados com critério — 200, 201, 204, 400, 404 e 500 — já se comunica quase tudo que uma aplicação precisa dizer.

O que faz diferença é o hábito: antes de escrever o return, perguntar o que aquele número está instruindo o cliente a fazer. Se a resposta for "tentar de novo" quando não há nada a tentar, o código está errado — por mais correto que o JSON esteja.