Os status HTTP em API REST Spring Boot são fundamentais para indicar corretamente o resultado de uma requisição.
Neste guia, você vai entender quais códigos HTTP usar, quando aplicá-los e como retorná-los corretamente em APIs REST desenvolvidas em Java com Spring Boot.
Este conteúdo complementa o guia principal sobre
API REST Spring Boot Java
e 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 ao cliente o resultado de uma requisição HTTP.
Eles fazem parte do protocolo HTTP e são essenciais para a comunicação entre cliente e servidor em uma API REST.
Em uma api rest spring boot java, o uso correto dos status HTTP melhora a clareza da API, facilita integrações e reduz ambiguidades.
Principais categorias de Status HTTP
1xx – Informativo
Indicam que a requisição foi recebida e está sendo processada.
2xx – Sucesso
Indicam que a requisição foi processada com sucesso.
3xx – Redirecionamento
Indicam que o cliente precisa realizar outra ação.
4xx – Erro do cliente
Indicam erro na requisição enviada pelo cliente.
5xx – Erro do servidor
Indicam falha no processamento da requisição no servidor.
Status HTTP mais usados em APIs REST
- 200 OK – Requisição bem-sucedida
- 201 Created – Recurso criado com sucesso
- 204 No Content – Sucesso sem retorno no corpo
- 400 Bad Request – Erro na requisição do cliente
- 401 Unauthorized – Usuário não autenticado
- 403 Forbidden – Acesso negado
- 404 Not Found – Recurso não encontrado
- 500 Internal Server Error – Erro interno no servidor
Como retornar Status HTTP no Spring Boot
A forma mais recomendada de retornar status HTTP em uma API REST é utilizando
ResponseEntity no Spring Boot,
pois ele permite controlar explicitamente o status e o corpo da resposta.
Exemplo com 200 OK
@GetMapping("/usuarios")
public ResponseEntity<List<String>> listarUsuarios() {
return ResponseEntity.ok(List.of("Ana", "Carlos", "João"));
}
Exemplo com 201 Created
@PostMapping("/usuarios")
public ResponseEntity<String> criarUsuario() {
return ResponseEntity.status(HttpStatus.CREATED)
.body("Usuário criado com sucesso");
}
Quando usar cada Status HTTP?
- 200 OK: buscas e operações bem-sucedidas
- 201 Created: criação de recursos
- 204 No Content: sucesso sem retorno
- 400 Bad Request: dados inválidos
- 401 / 403: problemas de autenticação ou autorização
- 404 Not Found: recurso inexistente
- 500 Internal Server Error: falhas inesperadas
Status HTTP e boas práticas em API REST
- Não use sempre 200 OK
- Retorne status coerentes com a operação
- Padronize respostas de erro
- Use ResponseEntity para maior controle
Status HTTP e Controllers no Spring Boot
Em APIs REST, os status HTTP são normalmente retornados a partir de classes anotadas com
@RestController.
Se você ainda tem dúvidas sobre essa anotação, veja a diferença entre
Controller vs RestController no Spring Boot.
Conteúdos relacionados
Conclusão
O uso correto dos status HTTP em API REST Spring Boot é essencial para criar APIs claras, previsíveis e profissionais.
Com Spring Boot e ResponseEntity, é possível controlar facilmente os códigos HTTP e entregar respostas mais semânticas e alinhadas às boas práticas REST.