Resposta rápida: em uma API REST com Spring Boot, use status HTTP para dizer exatamente o que aconteceu na requisição. Para listar dados, normalmente use 200 OK; para criar, 201 Created; para remover sem retorno, 204 No Content; e, em caso de erro, escolha um código coerente como 400, 401, 403 ou 404.
Usar status HTTP em API REST Spring Boot do jeito certo melhora a leitura da API, facilita a integração com frontend e deixa o tratamento de erro muito mais previsível. Se a sua resposta diz só “deu certo” ou “deu errado”, você perde informação importante para quem consome a API.
Este conteúdo complementa o guia principal sobre API REST Spring Boot Java e também o uso de ResponseEntity no Spring Boot.
O que são status HTTP?
Status HTTP são códigos numéricos retornados pelo servidor para informar o resultado de uma requisição. Eles fazem parte do protocolo HTTP e são essenciais em qualquer API REST, porque ajudam o cliente a entender se a operação foi concluída, se houve validação inválida ou se ocorreu uma falha no servidor.
Em uma API REST feita com Spring Boot, esses códigos não servem só para “decorar” a resposta. Eles fazem parte da comunicação da API e devem refletir o que realmente aconteceu.
Principais categorias de status HTTP
1xx – Informativo
Indicam que a requisição foi recebida e está em processamento.
2xx – Sucesso
Indicam que a requisição foi processada corretamente.
3xx – Redirecionamento
Indicam que o cliente precisa seguir outra rota ou ação.
4xx – Erro do cliente
Indicam que existe algum problema na requisição enviada, como dados inválidos, falta de autenticação ou ausência de permissão.
5xx – Erro do servidor
Indicam falhas internas durante o processamento da requisição.
Status HTTP mais usados em APIs REST
- 200 OK – Requisição concluída com sucesso
- 201 Created – Recurso criado com sucesso
- 204 No Content – Sucesso sem corpo na resposta
- 400 Bad Request – Dados inválidos ou requisição malformada
- 401 Unauthorized – Usuário não autenticado
- 403 Forbidden – Acesso negado
- 404 Not Found – Recurso não encontrado
- 409 Conflict – Conflito com o estado atual do recurso
- 500 Internal Server Error – Erro inesperado no servidor
Como retornar status HTTP no Spring Boot
A forma mais comum e clara de retornar status HTTP em uma API REST é usando ResponseEntity. Com ele, você controla o código HTTP e o corpo da resposta de forma explícita.
Exemplo real: listar usuários com 200 OK
@RestController
@RequestMapping("/usuarios")
public class UsuarioController {
@GetMapping
public ResponseEntity<List<String>> listarUsuarios() {
List<String> usuarios = List.of("Ana", "Carlos", "João");
return ResponseEntity.ok(usuarios);
}
}Exemplo real: criar usuário com 201 Created
@PostMapping
public ResponseEntity<String> criarUsuario() {
// lógica de criação omitida
return ResponseEntity.status(HttpStatus.CREATED)
.body("Usuário criado com sucesso");
}Exemplo real: remover usuário com 204 No Content
@DeleteMapping("/{id}")
public ResponseEntity<Void> removerUsuario(@PathVariable Long id) {
// lógica de exclusão omitida
return ResponseEntity.noContent().build();
}Exemplo real com validação e erro 400
Quando a requisição vem com dados inválidos, o ideal é responder com 400 Bad Request. Isso deixa claro que o problema está no que o cliente enviou.
@PostMapping("/usuarios")
public ResponseEntity<String> criarUsuario(@RequestBody UsuarioDTO dto) {
if (dto.nome() == null || dto.nome().isBlank()) {
return ResponseEntity.badRequest().body("O campo nome é obrigatório");
}
return ResponseEntity.status(HttpStatus.CREATED)
.body("Usuário criado com sucesso");
}Bloco prático: quando usar cada status na prática
- 200 OK: retornar um recurso, uma lista ou uma operação concluída sem criação
- 201 Created: criar usuário, produto, pedido ou qualquer recurso novo
- 204 No Content: excluir ou atualizar algo sem necessidade de resposta no corpo
- 400 Bad Request: campo obrigatório ausente, formato inválido, regra de validação quebrada
- 401 Unauthorized: token ausente ou inválido
- 403 Forbidden: usuário autenticado, mas sem permissão
- 404 Not Found: ID inexistente ou rota inválida
- 409 Conflict: tentativa de criar recurso duplicado
- 500 Internal Server Error: exceção inesperada no servidor
Bloco de erro comum
Erro comum: retornar 200 OK para qualquer situação, inclusive quando houve falha de validação ou quando o recurso não foi encontrado.
Por que isso é um problema? Porque o cliente passa a interpretar erro como sucesso. Em integrações com frontend, logs, monitoramento e testes automatizados, isso gera comportamento incorreto e dificulta a manutenção da API.
Como corrigir: use o status HTTP correspondente ao cenário real e mantenha o corpo da resposta coerente com o código retornado.
Como tratar erro 404 no Spring Boot
Quando um recurso não existe, retorne 404 Not Found. Um caso clássico é buscar um usuário por ID e não encontrar o registro.
@GetMapping("/{id}")
public ResponseEntity<String> buscarUsuario(@PathVariable Long id) {
boolean existe = false; // exemplo simplificado
if (!existe) {
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.body("Usuário não encontrado");
}
return ResponseEntity.ok("Usuário encontrado");
}Boas práticas para status HTTP em API REST
- Não use 200 OK para tudo
- Escolha o status de acordo com a intenção da operação
- Padronize as mensagens de erro da API
- Use ResponseEntity no Spring Boot para ter controle explícito da resposta
- Para erros de validação e exceções, considere centralizar o tratamento com @ControllerAdvice e @ExceptionHandler
Como os status HTTP se encaixam nos controllers
Em aplicações com Spring Boot, a resposta normalmente sai de classes anotadas com @RestController. Se você quiser entender melhor essa diferença, vale ver o conteúdo sobre Controller vs RestController no Spring Boot.
FAQ sobre status HTTP em Spring Boot
Qual status HTTP devo usar para sucesso em uma consulta?
Normalmente, 200 OK. Se a consulta não retornar corpo, 204 No Content também pode fazer sentido em alguns cenários.
Quando usar 201 Created?
Use quando um novo recurso for criado com sucesso, como ao cadastrar um usuário ou salvar um pedido.
401 e 403 são a mesma coisa?
Não. 401 Unauthorized indica que o usuário não está autenticado. 403 Forbidden indica que ele está autenticado, mas não tem permissão.
Posso usar ResponseEntity em todos os endpoints?
Sim. Em APIs REST, essa é uma das formas mais práticas de controlar o status HTTP e o corpo da resposta.
Qual status usar quando o ID não existe?
O mais comum é 404 Not Found.
Conteúdos relacionados
- API REST Spring Boot Java
- ResponseEntity no Spring Boot
- Controller vs RestController no Spring Boot
- Paginação e Ordenação no Spring Boot com Spring Data JPA
Conclusão
Usar corretamente os status HTTP em API REST Spring Boot deixa sua API mais profissional, previsível e fácil de integrar. Com ResponseEntity, você consegue retornar códigos coerentes com a operação e evitar respostas genéricas que escondem erros reais.
Se você estiver construindo uma API mais completa, o próximo passo é centralizar o tratamento de exceções, padronizar mensagens de erro e revisar cada endpoint para garantir que o status HTTP represente de fato o resultado da operação.
Leitura complementar
Se quiser aprofundar esse assunto com um material mais atual, leia também Spring Security com JWT na prática: como proteger APIs REST com Spring Boot do zero.
Veja também Como tratar exceções no Spring Boot com @ControllerAdvice e @ExceptionHandler.
Se a sua API já cresce em volume de dados, confira Paginação e Ordenação no Spring Boot com Spring Data JPA: como montar APIs escaláveis.
Para ampliar a base técnica, acesse Guia de Java para backend: fundamentos, Spring e próximos passos.
Leitura complementar
Se voce quiser aprofundar esse assunto com um material mais atual, leia tambem Spring boot 422 ou 400 validacao api rest: erros comuns e ajuste.