Lección 6 de 8: validación y manejo de errores. Tu API ya guarda datos, pero acepta cualquier cosa y, cuando algo falla, responde con mensajes que no ayudan a nadie. Aquí aprenderás a rechazar los datos inválidos con Bean Validation y @Valid, a responder errores claros en un formato estándar con @RestControllerAdvice y ProblemDetail, y a no filtrar secretos en los errores.
Nunca confíes en lo que llega
Tu API la va a usar una app, un sitio web o un script de alguien más, y cualquiera puede mandar cualquier cosa: un nombre vacío, un precio negativo, un texto de diez mil caracteres. Si lo guardas sin revisar, el error aparece semanas después, en un reporte que suma mal. La regla es revisar los datos en la puerta, antes de que lleguen a tu lógica, y responder un error que explique qué está mal.
Bean Validation: las reglas van en el record
Bean Validation (Jakarta Validation) es el estándar de Java para declarar reglas con anotaciones. Spring Boot lo trae con la dependencia Validation de start.spring.io, spring-boot-starter-validation, que incluye Hibernate Validator. Las reglas se ponen en lo que recibe el controlador. Separamos lo que manda el cliente (NuevoProducto, sin id) de lo que guardamos (Producto):
package com.ejemplo.catalogo;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
import jakarta.validation.constraints.PositiveOrZero;
import jakarta.validation.constraints.Size;
import java.math.BigDecimal;
public record NuevoProducto(
@NotBlank(message = "el nombre es obligatorio")
@Size(max = 80, message = "el nombre admite hasta 80 caracteres")
String nombre,
@NotNull(message = "el precio es obligatorio")
@Positive(message = "el precio debe ser mayor que cero")
BigDecimal precio,
@PositiveOrZero(message = "las existencias no pueden ser negativas")
int existencias) {
}- AnotaciónExige que…
@NotNullel valor exista (no seanull)@NotBlankel texto tenga al menos un carácter que no sea espacio@Size(min, max)el texto o la lista tenga ese tamaño@Positive,@PositiveOrZeroel número sea mayor que cero, o mayor o igual@Min,@Max,@DecimalMin,@DecimalMaxel número esté en un rango@Email,@Pattern(regexp)el texto tenga forma de correo, o cumpla una expresión regular@Past,@Futurela fecha sea pasada o futura
Ojo con @Positive sobre un BigDecimal: si el campo no viene, vale null y la regla lo deja pasar, porque casi todas las anotaciones consideran válido el null. Por eso el precio lleva además @NotNull. El texto de message es lo que verá el cliente; sin él, Hibernate Validator usa su mensaje de fábrica, que en un servidor con el idioma en inglés sale como «must be greater than 0».
@Valid: activar la revisión
Las anotaciones del record no hacen nada solas. Para que Spring las revise al recibir la petición, el parámetro lleva @Valid:
package com.ejemplo.catalogo;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Positive;
import java.math.BigDecimal;
import java.net.URI;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/productos")
public class ProductoController {
private final ProductoService servicio;
public ProductoController(ProductoService servicio) {
this.servicio = servicio;
}
@PostMapping
public ResponseEntity<Producto> crear(@Valid @RequestBody NuevoProducto nuevo) {
Producto p = servicio.crear(nuevo);
return ResponseEntity.created(URI.create("/productos/" + p.id())).body(p);
}
@GetMapping("/{id}")
public Producto uno(@PathVariable long id) {
return servicio.buscar(id);
}
@GetMapping
public List<Producto> hasta(@RequestParam @Positive BigDecimal max) {
return servicio.hasta(max);
}
@GetMapping("/{id}/reporte")
public String reporte(@PathVariable long id) {
throw new IllegalStateException("No pude conectar a db-interna.ejemplo.com:5432 con el usuario admin_tienda");
}
}Si los datos cumplen, tu método se ejecuta como siempre. Si no, Spring ni siquiera lo llama: responde 400 por su cuenta. Así se ve, con un producto válido, uno inválido y uno que no existe:
terminal$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25}'
{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25}
$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"","precio":-5,"existencias":-1}'
{"timestamp":"2026-11-22T16:15:11.793Z","status":400,"error":"Bad Request","path":"/productos"}
$ curl -s localhost:8080/productos/99
{"timestamp":"2026-11-22T16:15:11.818Z","status":500,"error":"Internal Server Error","path":"/productos/99"}El 400 funciona, pero el cliente no sabe qué corregir. Y el 404 salió como un 500, porque nuestra excepción ProductoNoEncontradoException no le dice a Spring qué código usar. El registro del servidor sí tiene los detalles:
registro de la aplicación2026-11-22T10:15:11.788-06:00 WARN 95 --- [valid-basico] [nio-8080-exec-2] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public org.springframework.http.ResponseEntity<com.ejemplo.catalogo.Producto> com.ejemplo.catalogo.ProductoController.crear(com.ejemplo.catalogo.NuevoProducto) with 3 errors: [Field error in object 'nuevoProducto' on field 'existencias': rejected value [-1]; codes [PositiveOrZero.nuevoProducto.existencias,PositiveOrZero.existencias,PositiveOrZero.int,PositiveOrZero]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [nuevoProducto.existencias,existencias]; arguments []; default message [existencias]]; default message [las existencias no pueden ser negativas]] [Field error in object 'nuevoProducto' on field 'precio': rejected value [-5]; codes [Positive.nuevoProducto.precio,Positive.precio,Positive.java.math.BigDecimal,Positive]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [nuevoProducto.precio,precio]; arguments []; default message [precio]]; default message [el precio debe ser mayor que cero]] [Field error in object 'nuevoProducto' on field 'nombre': rejected value []; codes [NotBlank.nuevoProducto.nombre,NotBlank.nombre,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [nuevoProducto.nombre,nombre]; arguments []; default message [nombre]]; default message [el nombre es obligatorio]] ]
ProblemDetail: un formato estándar para los errores
Cada API inventaba su propio formato de error hasta que se publicó un estándar: el RFC 9457, «Problem Details for HTTP APIs». Define un JSON con los campos type, title, status, detail e instance, con el tipo de contenido application/problem+json. Spring lo implementa con la clase ProblemDetail, y Spring Boot lo enciende con una línea en application.properties:
spring.mvc.problemdetails.enabled=true
terminal$ curl -i -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"","precio":-5,"existencias":-1}'
HTTP/1.1 400
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sun, 22 Nov 2026 16:15:06 GMT
Connection: close
{"detail":"Invalid request content.","status":400,"title":"Bad Request"}Mejor: el formato es estándar y el Content-Type lo anuncia. Spring escribe solo los campos que tienen valor: omite type cuando sería el genérico about:blank, y instance cuando no se definió. Pero el detail sigue siendo genérico. Para el último paso, un manejador propio.
@RestControllerAdvice: un solo lugar para todos los errores
Una clase con @RestControllerAdvice atiende las excepciones de todos los controladores. Cada método marcado con @ExceptionHandler se encarga de un tipo de excepción y devuelve la respuesta. Al heredar de ResponseEntityExceptionHandler, recibes ya resueltos los errores propios de Spring MVC (415, 405, 400…) en formato ProblemDetail, y puedes cambiar solo los que te interesen:
package com.ejemplo.catalogo;
import java.util.Map;
import java.util.TreeMap;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
@RestControllerAdvice
public class ManejoDeErrores extends ResponseEntityExceptionHandler {
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
HttpHeaders headers, HttpStatusCode status, WebRequest request) {
ProblemDetail problema = ex.getBody();
problema.setTitle("Datos no válidos");
problema.setDetail("Revisa los campos de la lista de errores");
Map<String, String> errores = new TreeMap<>();
ex.getBindingResult().getFieldErrors().forEach(e -> errores.put(e.getField(), e.getDefaultMessage()));
problema.setProperty("errores", errores);
return handleExceptionInternal(ex, problema, headers, status, request);
}
@ExceptionHandler(ProductoNoEncontradoException.class)
public ProblemDetail noEncontrado(ProductoNoEncontradoException ex) {
ProblemDetail problema = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
problema.setTitle("Producto no encontrado");
return problema;
}
}El primer método sobrescribe la respuesta a los datos inválidos: toma el ProblemDetail que Spring ya armó, le cambia el título y el detalle, y agrega una propiedad errores con el mensaje de cada campo. El segundo convierte nuestra excepción en un 404 con un mensaje claro. El controlador no cambió en nada: sigue lanzando la excepción, y el aviso la traduce.
terminal$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"","precio":-5,"existencias":-1}'
{"detail":"Revisa los campos de la lista de errores","status":400,"title":"Datos no válidos","errores":{"existencias":"las existencias no pueden ser negativas","nombre":"el nombre es obligatorio","precio":"el precio debe ser mayor que cero"}}
$ curl -s localhost:8080/productos/99
{"detail":"No existe el producto 99","status":404,"title":"Producto no encontrado"}
$ curl -s "localhost:8080/productos?max=-1"
{"detail":"Validation failure","status":400,"title":"Bad Request"}
$ curl -s "localhost:8080/productos?max=2000"
[{"id":1,"nombre":"Teclado mecánico","precio":1299.00,"existencias":8}]Ahora el cliente sabe exactamente qué corregir, y cada error tiene su código. La tercera petición muestra algo que no programaste: @Positive sobre el @RequestParam también se revisa, porque Spring valida los parámetros de los métodos del controlador cuando llevan reglas. El error sale en el mismo formato.
Ojo con la seguridad: los errores 500 no deben contar tus secretos
El método reporte del controlador falla a propósito con un mensaje que trae el nombre del servidor de la base de datos y el usuario. Mira qué recibe el cliente:
terminal$ curl -s localhost:8080/productos/1/reporte
{"timestamp":"2026-11-22T16:15:06.209Z","status":500,"error":"Internal Server Error","path":"/productos/1/reporte"}Nada del mensaje: por omisión, Spring Boot no incluye el texto de la excepción ni la traza en la respuesta (server.error.include-message e include-stacktrace valen never). El detalle completo queda solo en el registro del servidor, donde debe estar. No cambies esos ajustes en producción, y no copies ex.getMessage() a la respuesta en tus manejadores salvo en excepciones tuyas, cuyo mensaje escribiste pensando en el cliente, como la de producto no encontrado.
El error que te ahorra: olvidar @Valid
Es el error más común de esta lección, y el más peligroso porque no avisa: con las reglas en el record pero sin @Valid en el parámetro, nada se revisa:
terminal$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"","precio":-5,"existencias":-1}'
{"id":2,"nombre":"","precio":-5,"existencias":-1}Se guardó un producto sin nombre, con precio de -5 y existencias negativas, y la respuesta fue un alegre 201. Ninguna herramienta lo detecta por ti: la única defensa es una prueba que mande datos inválidos y espere un 400, como las de la lección 7.
Retos
Reto 1. Agrega a NuevoProducto un campo sku obligatorio con la forma ABC-1234: tres letras mayúsculas, un guion y cuatro dígitos.
Ver la solución
@NotBlank(message = "el SKU es obligatorio")
@Pattern(regexp = "[A-Z]{3}-\\d{4}", message = "el SKU debe tener la forma ABC-1234")
String skuterminal$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"Mouse","precio":349.50,"existencias":25,"sku":"mou-12"}'
{"detail":"Revisa los campos de la lista de errores","status":400,"title":"Datos no válidos","errores":{"sku":"el SKU debe tener la forma ABC-1234"}}
$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"Mouse","precio":349.50,"existencias":25,"sku":"MOU-0012"}'
{"id":2,"nombre":"Mouse","precio":349.50,"existencias":25}El segundo producto pasa la validación; la respuesta no trae el SKU porque, en este ejemplo, Producto no lo guarda. @Pattern exige que el texto completo cumpla la expresión, no solo una parte. Dentro de un texto de Java, la diagonal invertida de \d se escribe doble. Si las expresiones regulares te dan dolor de cabeza, tenemos una guía para principiantes.
Reto 2. Sin ejecutarlo: con @Valid en su lugar, ¿qué responde el POST si el JSON trae "existencias": "muchas"?
Ver la solución
Un 400, pero no por la validación: Jackson no puede convertir "muchas" en un int, así que falla al leer el cuerpo, antes de llegar a @Valid. Es la misma excepción que viste en la lección 3 con el precio «barato» (HttpMessageNotReadableException), y con ResponseEntityExceptionHandler también sale como ProblemDetail. Si quieres un mensaje propio para ese caso, sobrescribe handleHttpMessageNotReadable.
Reto 3. ¿Por qué no basta con validar en la app o en la página web que llama a tu API?
Ver la solución
Porque cualquiera puede llamar a tu API sin pasar por esa app: con curl, con Postman o con un script. La validación del lado del cliente es comodidad para el usuario (le avisa antes de enviar); la del servidor es la que protege tus datos. Hacen falta las dos, y la del servidor nunca se puede saltar.
Cada proyecto de esta lección se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin acceso a la red, se arrancó y se le hicieron las peticiones que ves con curl antes de publicar la lección; los registros, las respuestas y los errores están copiados de esa ejecución. Las horas de los registros son de la Ciudad de México.
