Spring Boot Course · Lesson 7

Validation & Error Handling

Your API trusts whatever it's sent. Post a book with a blank title, a negative year, or an authorIds entry that matches no one, and it either stores garbage or blows up with a raw 500. In this lesson you'll make it reject bad input at the door and report every failure the same way — one clean, structured error response across the whole API.

The win

Two upgrades that together make the API feel professional. Bean Validation rejects malformed requests with a 400 that names exactly which fields are wrong. And a single @RestControllerAdvice turns every error — validation failures, missing resources, bad references — into one consistent Problem Detail body. Along the way both rough edges from Lesson 6 get fixed — the 500 for a bad authorIds entry becomes a clean 404, the 500 for deleting an author who still has books becomes a 409 Conflict — and the Optional-juggling controllers from Lessons 4–6 get noticeably thinner.

Two jobs, one place they meet

"Error handling" really splits into two questions:

Is this request even acceptable? — reject bad input before any logic runs. That's validation.
When something goes wrong, what do we send back? — turn failures into a consistent HTTP response. That's exception handling.

They meet in one component — a global handler — because a validation failure is just another exception to translate. You'll build validation first, then the handler that gives both halves a single, uniform voice.

Step 1 — Add the validation starter

Bean Validation isn't pulled in by the web starter, so add it explicitly. It brings Hibernate Validator (the reference implementation of the Jakarta Bean Validation spec).


37 collapsed lines
1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4
    <modelVersion>4.0.0</modelVersion>
5
    <parent>
6
        <groupId>org.springframework.boot</groupId>
7
        <artifactId>spring-boot-starter-parent</artifactId>
8
        <version>4.1.1</version>
9
        <relativePath/> <!-- lookup parent from repository -->
10
    </parent>
11
    <groupId>com.example</groupId>
12
    <artifactId>library</artifactId>
13
    <version>0.0.1-SNAPSHOT</version>
14
    <name>library</name>
15
    <description/>
16
    <url/>
17
    <licenses>
18
        <license/>
19
    </licenses>
20
    <developers>
21
        <developer/>
22
    </developers>
23
    <scm>
24
        <connection/>
25
        <developerConnection/>
26
        <tag/>
27
        <url/>
28
    </scm>
29
    <properties>
30
        <java.version>21</java.version>
31
    </properties>
32
    <dependencies>
33
        <dependency>
34
            <groupId>org.springframework.boot</groupId>
35
            <artifactId>spring-boot-starter-webmvc</artifactId>
36
        </dependency>
37

38
        <!-- Bean Validation (@Valid + constraints); brings Hibernate Validator -->
39
        <dependency>
40
            <groupId>org.springframework.boot</groupId>
41
            <artifactId>spring-boot-starter-validation</artifactId>
42
        </dependency>
58 collapsed lines
43

44
        <!-- Spring Data JPA + Hibernate -->
45
        <dependency>
46
            <groupId>org.springframework.boot</groupId>
47
            <artifactId>spring-boot-starter-data-jpa</artifactId>
48
        </dependency>
49

50
        <!-- PostgreSQL JDBC driver (used at runtime to talk to the database) -->
51
        <dependency>
52
            <groupId>org.postgresql</groupId>
53
            <artifactId>postgresql</artifactId>
54
            <scope>runtime</scope>
55
        </dependency>
56

57
        <!-- Liquibase migrations. The autoconfiguration lives in this module (it brings
58
             liquibase-core transitively); the bare org.liquibase:liquibase-core won't activate it. -->
59
        <dependency>
60
            <groupId>org.springframework.boot</groupId>
61
            <artifactId>spring-boot-liquibase</artifactId>
62
        </dependency>
63

64
        <!-- Starts/stops the Postgres container from compose.yaml when the app runs -->
65
        <dependency>
66
            <groupId>org.springframework.boot</groupId>
67
            <artifactId>spring-boot-docker-compose</artifactId>
68
            <optional>true</optional>
69
        </dependency>
70

71
        <!-- Lombok: generates getters/constructors/equals at compile time -->
72
        <dependency>
73
            <groupId>org.projectlombok</groupId>
74
            <artifactId>lombok</artifactId>
75
            <optional>true</optional>
76
        </dependency>
77

78
        <!-- uuid-creator: time-ordered UUIDv7 generation -->
79
        <dependency>
80
            <groupId>com.github.f4b6a3</groupId>
81
            <artifactId>uuid-creator</artifactId>
82
            <version>6.0.0</version>  <!-- or the latest on Maven Central -->
83
        </dependency>
84

85
        <dependency>
86
            <groupId>org.springframework.boot</groupId>
87
            <artifactId>spring-boot-starter-webmvc-test</artifactId>
88
            <scope>test</scope>
89
        </dependency>
90
    </dependencies>
91

92
    <build>
93
        <plugins>
94
            <plugin>
95
                <groupId>org.springframework.boot</groupId>
96
                <artifactId>spring-boot-maven-plugin</artifactId>
97
            </plugin>
98
        </plugins>
99
    </build>
100

101
</project>

Step 2 — Constrain the request DTOs

The constraints go on the request DTOs — the shapes you accept at the boundary (Lesson 6) — not on the entity. Annotate each field with what "valid" means:

1
package com.example.library.book;
2

3
import java.util.Set;
4
import java.util.UUID;
5
import jakarta.validation.constraints.NotBlank;
6
import jakarta.validation.constraints.NotEmpty;
7
import jakarta.validation.constraints.Positive;
8

9
public record CreateBookRequest(
10
    @NotBlank String title,          // not null, and not just whitespace
11
    @Positive int year,              // must be > 0
12
    @NotEmpty Set<UUID> authorIds    // at least one author
13
) {}

1
package com.example.library.author;
2

3
import jakarta.validation.constraints.NotBlank;
4

5
public record CreateAuthorRequest(@NotBlank String name) {}

Why constraints belong on the DTO, not the entity

Validation is a property of the request you accept, so it lives on the request DTO — right where the boundary is. Putting @NotBlank on the entity instead would scatter input rules into your persistence model, validate at the wrong moment (on save, not on receipt), and tie your accepted-input rules to your storage. The DTO already exists to define "what we accept"; the constraints simply make that definition enforceable. (Common constraints: @NotNull, @NotBlank, @Size(min,max), @Positive, @Min/@Max, @Email, @Pattern.) @NotEmpty is the right constraint for a collection: it rejects both a missing field (null) and an empty array. (@NotNull alone would let [] through.)

Step 3 — Turn validation on with `@Valid`

Constraints do nothing until you ask Spring to check them. Add @Valid before each validated @RequestBody — that's the switch. Four methods take one: two in the book controller, two in the author controller.


5 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
34 collapsed lines
7
import org.springframework.http.ResponseEntity;
8
import org.springframework.web.bind.annotation.DeleteMapping;
9
import org.springframework.web.bind.annotation.GetMapping;
10
import org.springframework.web.bind.annotation.PathVariable;
11
import org.springframework.web.bind.annotation.PostMapping;
12
import org.springframework.web.bind.annotation.PutMapping;
13
import org.springframework.web.bind.annotation.RequestBody;
14
import org.springframework.web.bind.annotation.RequestMapping;
15
import org.springframework.web.bind.annotation.RequestParam;
16
import org.springframework.web.bind.annotation.RestController;
17

18
@RestController
19
@RequestMapping("/api/books")
20
public class BookController {
21

22
    private final BookService books;
23

24
    public BookController(BookService books) {
25
        this.books = books;
26
    }
27

28
    @GetMapping                                          // GET /api/books  or  ?authorId=...
29
    public List<BookResponse> all(@RequestParam(required = false) UUID authorId) {
30
        return books.findAll(authorId).stream().map(BookResponse::from).toList();
31
    }
32

33
    @GetMapping("/{id}")
34
    public ResponseEntity<BookResponse> byId(@PathVariable UUID id) {
35
        return books.findById(id)
36
            .map(BookResponse::from)
37
            .map(ResponseEntity::ok)
38
            .orElse(ResponseEntity.notFound().build());
39
    }
40

41
    @PostMapping                                         // POST /api/books
42
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
43
        Book saved = books.create(req.title(), req.year(), req.authorIds());
44
        URI location = URI.create("/api/books/" + saved.getId());
45
        return ResponseEntity.created(location).body(BookResponse.from(saved));
46
    }
47

48
    @PutMapping("/{id}")                                 // PUT /api/books/{id}
49
    public ResponseEntity<BookResponse> replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
50
        return books.replace(id, req.title(), req.year(), req.authorIds())
51
            .map(BookResponse::from)
52
            .map(ResponseEntity::ok)
53
            .orElse(ResponseEntity.notFound().build());
54
    }
7 collapsed lines
55

56
    @DeleteMapping("/{id}")                     // DELETE /api/books/{id}
57
    public ResponseEntity<Void> delete(@PathVariable UUID id) {
58
        return books.delete(id)
59
                ? ResponseEntity.noContent().build()
60
                : ResponseEntity.notFound().build();
61
    }
62
}


5 collapsed lines
1
package com.example.library.author;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
33 collapsed lines
7
import org.springframework.http.ResponseEntity;
8
import org.springframework.web.bind.annotation.DeleteMapping;
9
import org.springframework.web.bind.annotation.GetMapping;
10
import org.springframework.web.bind.annotation.PathVariable;
11
import org.springframework.web.bind.annotation.PostMapping;
12
import org.springframework.web.bind.annotation.PutMapping;
13
import org.springframework.web.bind.annotation.RequestBody;
14
import org.springframework.web.bind.annotation.RequestMapping;
15
import org.springframework.web.bind.annotation.RestController;
16

17
@RestController
18
@RequestMapping("/api/authors")
19
public class AuthorController {
20

21
    private final AuthorService authors;
22

23
    public AuthorController(AuthorService authors) {
24
        this.authors = authors;
25
    }
26

27
    @GetMapping
28
    public List<AuthorResponse> all() {
29
        return authors.findAll().stream().map(AuthorResponse::from).toList();
30
    }
31

32
    @GetMapping("/{id}")
33
    public ResponseEntity<AuthorResponse> byId(@PathVariable UUID id) {
34
        return authors.findById(id)
35
            .map(AuthorResponse::from)
36
            .map(ResponseEntity::ok)
37
            .orElse(ResponseEntity.notFound().build());
38
    }
39

40
    @PostMapping
41
    public ResponseEntity<AuthorResponse> create(@Valid @RequestBody CreateAuthorRequest req) {
42
        Author saved = authors.create(req.name());
43
        URI location = URI.create("/api/authors/" + saved.getId());
44
        return ResponseEntity.created(location).body(AuthorResponse.from(saved));
45
    }
46

47
    @PutMapping("/{id}")
48
    public ResponseEntity<AuthorResponse> replace(@PathVariable UUID id, @Valid @RequestBody CreateAuthorRequest req) {
49
        return authors.replace(id, req.name())
50
            .map(AuthorResponse::from)
51
            .map(ResponseEntity::ok)
52
            .orElse(ResponseEntity.notFound().build());
53
    }
7 collapsed lines
54

55
    @DeleteMapping("/{id}")
56
    public ResponseEntity<Void> delete(@PathVariable UUID id) {
57
        return authors.delete(id)
58
            ? ResponseEntity.noContent().build()
59
            : ResponseEntity.notFound().build();
60
    }
61
}

@Valid is the only change in all four methods — leave the method bodies and return types exactly as they are. (Those get simplified in Step 6, once the service throws; doing it now would be jumping ahead.) When a constraint fails, Spring aborts the method before your code runs and throws a MethodArgumentNotValidException. Out of the box that produces a 400 — but a generic one. Shaping it into something clean is the next step.

No @Valid, no validation

The constraint annotations are inert decoration without @Valid at the call site. If bad input is sailing through untouched, a missing @Valid is the first thing to check.

Step 4 — One error model: a global handler + Problem Detail

Now the centerpiece. Instead of each controller turning failures into responses, one class does it for the whole API. First, two small domain exceptions — one for each way a well-formed request can still be refused. "Not found":

1
package com.example.library.error;
2

3
// Thrown when an addressed (or referenced) resource doesn't exist. Handler maps it to 404.
4
public class NotFoundException extends RuntimeException {
5
    public NotFoundException(String message) {
6
        super(message);
7
    }
8
}

And "conflict" — the request is valid and the thing exists, but the current state of the data forbids the operation. You met this at the end of Lesson 6: deleting an author who still has books.

1
package com.example.library.error;
2

3
// Thrown when a request is valid but clashes with the current state of the data:
4
// deleting an author who still has books, or re-creating something that already exists. Handler maps it to 409.
5
public class ConflictException extends RuntimeException {
6
    public ConflictException(String message) {
7
        super(message);
8
    }
9
}

Then the handler. It's a @RestControllerAdvice — a class whose @ExceptionHandler methods apply across every controller — and it extends ResponseEntityExceptionHandler, Spring's base class that already maps all the standard MVC failures (malformed JSON, type mismatches, wrong method or media type, …) to ProblemDetail responses. So you inherit consistent handling for the framework's exceptions, and add just four things of your own: a handler for each of your two exceptions, a tweak to the validation response, and a last-resort catch-all.

1
package com.example.library.error;
2

3
import java.util.HashMap;
4
import java.util.Map;
5
import lombok.extern.slf4j.Slf4j;
6
import org.springframework.http.HttpHeaders;
7
import org.springframework.http.HttpStatus;
8
import org.springframework.http.HttpStatusCode;
9
import org.springframework.http.ProblemDetail;
10
import org.springframework.http.ResponseEntity;
11
import org.springframework.validation.FieldError;
12
import org.springframework.web.bind.MethodArgumentNotValidException;
13
import org.springframework.web.bind.annotation.ExceptionHandler;
14
import org.springframework.web.bind.annotation.RestControllerAdvice;
15
import org.springframework.web.context.request.WebRequest;
16
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
17

18
@Slf4j   // generates the private static final Logger log field
19
@RestControllerAdvice
20
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
21

22
    // Our own "missing resource" -> 404
23
    @ExceptionHandler(NotFoundException.class)
24
    public ProblemDetail handleNotFound(NotFoundException ex) {
25
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
26
        problem.setTitle("Resource not found");
27
        return problem;
28
    }
29

30
    // A valid request that the current state of the data forbids -> 409
31
    @ExceptionHandler(ConflictException.class)
32
    public ProblemDetail handleConflict(ConflictException ex) {
33
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
34
        problem.setTitle("Conflict");
35
        return problem;
36
    }
37

38
    // The parent already turns a validation failure into a 400 ProblemDetail;
39
    // we OVERRIDE its handler only to attach a field -> message map.
40
    @Override
41
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
42
            MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
43
        ProblemDetail problem = ex.getBody();          // the ProblemDetail Spring already built
44
        problem.setTitle("Validation failed");
45
        problem.setDetail("One or more fields are invalid.");
46
        Map<String, String> errors = new HashMap<>();
47
        for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
48
            errors.put(fieldError.getField(), fieldError.getDefaultMessage());
49
        }
50
        problem.setProperty("errors", errors);
51
        return handleExceptionInternal(ex, problem, headers, status, request);
52
    }
53

54
    // Last resort: anything not matched above -> 500. Log the real cause; tell the client nothing.
55
    @ExceptionHandler(Exception.class)
56
    public ProblemDetail handleUnexpected(Exception ex) {
57
        log.error("Unhandled exception", ex);
58
        return ProblemDetail.forStatusAndDetail(
59
            HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred.");
60
    }
61
}

What @RestControllerAdvice and ProblemDetail buy you

@RestControllerAdvice is a @ControllerAdvice whose handler return values are written to the response body (the same way @RestController works). Its @ExceptionHandler methods catch exceptions from every controller, so error formatting lives in exactly one place — change it once, the whole API changes. ProblemDetail is Spring's representation of RFC 9457: a standard error body with type, title, status, detail, and instance, plus any custom members you add (our errors map). Returning it sets the application/problem+json content type and the status automatically.

Why extend ResponseEntityExceptionHandler (and override, not re-add, validation)

Your own handlers only cover the exceptions you name. Everything else — a malformed JSON body, /api/books/not-a-uuid, a PATCH on a route that has none, a wrong Content-Type — is thrown by Spring before your code runs. Left alone, those fall through to Spring Boot's default error page (a different body shape, breaking your one-contract goal). Extending ResponseEntityExceptionHandler gives you correct, ProblemDetail-shaped responses for all of them for free:

a malformed JSON body → 400
a path or query value of the wrong type, such as an id that isn't a UUID → 400
a method the route doesn't support → 405
a Content-Type the endpoint can't read → 415

That's also why validation is an @Override of handleMethodArgumentNotValid, not a fresh @ExceptionHandler: the parent already handles that exception, so you hook its existing ProblemDetail (ex.getBody()), attach your errors map, and hand it back — rather than duplicating (and fighting) the parent's handler.

The catch-all: two rules that matter

The @ExceptionHandler(Exception.class) is the safety net for the genuinely unexpected — a database constraint violation, an NullPointerException — so nothing ever escapes as a raw stack trace.

Log the cause, leak nothing. Record the real exception server-side (log.error), but return a generic message. Echoing ex.getMessage() or a stack trace to clients exposes internals — a real security mistake.
It's greedy — order saves you. Exception is the supertype of everything, so on its own this handler would swallow the framework's 4xx and turn a bad-UUID 400 into a 500. Because you extend ResponseEntityExceptionHandler, its specific handlers out-rank Exception.class (Spring picks the most specific match), so the catch-all only fires for what nothing else claimed.

Step 5 — Make the services throw

With a handler in place, the layers below stop returning "absence" and start throwing when something's missing. The service becomes the single source of the not-found decision:


8 collapsed lines
1
package com.example.library.book;
2

3
import java.util.HashSet;
4
import java.util.List;
5
import java.util.Set;
6
import java.util.UUID;
7
import com.example.library.author.Author;
8
import com.example.library.author.AuthorRepository;
9
import com.example.library.error.NotFoundException;   // new; Optional and NoSuchElementException are no longer needed
17 collapsed lines
10
import org.springframework.stereotype.Service;
11

12
@Service
13
public class BookService {
14

15
    private final BookRepository books;
16
    private final AuthorRepository authors;            // new: to resolve author ids
17

18
    public BookService(BookRepository books, AuthorRepository authors) {
19
        this.books = books;
20
        this.authors = authors;
21
    }
22

23
    public List<Book> findAll(UUID authorId) {
24
        return (authorId == null) ? books.findAll() : books.findByAuthorsId(authorId);
25
    }
26

27
    // Replaces findById: the service now decides "not found" and throws instead of returning an Optional.
28
    public Book getById(UUID id) {
29
        return books.findById(id)
30
            .orElseThrow(() -> new NotFoundException("No book with id " + id));
31
    }
6 collapsed lines
32

33
    public Book create(String title, int year, Set<UUID> authorIds) {
34
        Book book = new Book(title, year, requireAuthors(authorIds));
35
        return books.save(book);
36
    }
37

38
    public Book replace(UUID id, String title, int year, Set<UUID> authorIds) {
39
        if (!books.existsById(id)) {
40
            throw new NotFoundException("No book with id " + id);
41
        }
42
        Book book = new Book(title, year, requireAuthors(authorIds));
43
        book.setId(id);
44
        return books.save(book);
45
    }
46

47
    public void delete(UUID id) {
48
        if (!books.existsById(id)) {
49
            throw new NotFoundException("No book with id " + id);
50
        }
51
        books.deleteById(id);
52
    }
53

54
    // Every id must resolve to a real author, or the book isn't created at all.
55
    private Set<Author> requireAuthors(Set<UUID> authorIds) {
56
        List<Author> found = authors.findAllById(authorIds);
57
        if (found.size() != authorIds.size()) {
58
            Set<UUID> missing = new HashSet<>(authorIds);
59
            found.forEach(a -> missing.remove(a.getId()));
60
            throw new NotFoundException("No author with id " + missing);
61
        }
62
        return new HashSet<>(found);
63
    }
64
}

That last method is the fix for Lesson 6's deliberate rough edge: requireAuthors already threw, but as an unhandled exception it surfaced as a blunt 500. Now it throws NotFoundException — and because it names every missing id in the message, a client that sent three ids and mistyped one is told exactly which.

Why findById became getById

A naming convention worth adopting: find… means "might not be there" (returns an Optional, caller handles absence), while get… means "should be there" (returns the value directly, or throws). The contract just flipped — from an empty Optional to throwing — so the name flips too; leaving it findById would mislead callers into expecting an Optional. It's an established idiom, not an official Java rule — the clearest statement is Stephen Colebourne's Naming Optional query methods (he led java.time/JSR-310). You already use the find half: the repository's findById returns Optional — and the service's getById wraps it with .orElseThrow(...), marking the exact point where "maybe absent" becomes "here, or fail."

Bad authorIds: why 404 (and what else it could be)

Posting a book where any entry in authorIds matches no author returns 404 — "the author you referenced doesn't exist." That's a defensible, common choice. Some teams argue a referenced-entity problem in the request body is better expressed as 422 Unprocessable Entity (the request was well-formed but can't be fulfilled) or 400 Bad Request. Any of the three is reasonable; what matters is that it's a deliberate 4xx with a clear message, not an accidental 500. We use one NotFoundException for both missing-path and missing-reference to keep the model simple.

The author service gets the same treatment — and it's where Lesson 6's other rough edge gets fixed. Deleting an author who still has books ran into the foreign key and came back as a 500. The service should ask first. That takes one more derived query on the book repository; existsBy… makes Spring Data generate an EXISTS check instead of loading anything:

1
package com.example.library.book;
2

3
import java.util.List;
4
import java.util.UUID;
5
import org.springframework.data.jpa.repository.JpaRepository;
6

7
public interface BookRepository extends JpaRepository<Book, UUID> {
8

9
    // Traverses the collection: WHERE any of the book's authors has this id
10
    List<Book> findByAuthorsId(UUID authorId);
11

12
    // Is any book still linked to this author? (Spring Data derives an EXISTS query.)
13
    boolean existsByAuthorsId(UUID authorId);
14
}

1
package com.example.library.author;
2

3
import java.util.List;
4
import java.util.UUID;
5
import com.example.library.book.BookRepository;
6
import com.example.library.error.ConflictException;
7
import com.example.library.error.NotFoundException;
8
import org.springframework.stereotype.Service;
9

10
@Service
11
public class AuthorService {
12

13
    private final AuthorRepository authors;
14
    private final BookRepository books;              // to ask: does this author still have books?
15

16
    public AuthorService(AuthorRepository authors, BookRepository books) {
17
        this.authors = authors;
18
        this.books = books;
19
    }
20

21
    public List<Author> findAll() {
22
        return authors.findAll();
23
    }
24

25
    public Author getById(UUID id) {
26
        return authors.findById(id)
27
            .orElseThrow(() -> new NotFoundException("No author with id " + id));
28
    }
29

30
    public Author create(String name) {
31
        return authors.save(new Author(name));
32
    }
33

34
    public Author replace(UUID id, String name) {
35
        if (!authors.existsById(id)) {
36
            throw new NotFoundException("No author with id " + id);
37
        }
38
        Author author = new Author(name);
39
        author.setId(id);
40
        return authors.save(author);
41
    }
42

43
    public void delete(UUID id) {
44
        if (!authors.existsById(id)) {
45
            throw new NotFoundException("No author with id " + id);
46
        }
47
        if (books.existsByAuthorsId(id)) {
48
            throw new ConflictException("Author " + id + " still has books; delete or re-author them first");
49
        }
50
        authors.deleteById(id);
51
    }
52
}

404 vs. 409: two different refusals

Both are the client's problem, but they say different things. 404: the thing you named isn't there — nothing the client does to the rest of the data will change that. 409 Conflict: it's there, and your request is fine, but the data's current state won't allow it — change that state (delete or re-author the books) and the very same request succeeds. Picking the right one tells the client whether to give up or to fix something and retry.

Note what did not change: the foreign key is still in the database. The service's check makes the common case polite; the constraint remains the guarantee. If a book were linked to the author in the instant between the check and the delete, the key would still refuse — and the catch-all would report a 500, which for a genuine race is an honest answer.

Step 6 — Thin out the controllers

Because the service throws and the advice handles, the controllers shed all their Optional-to-status plumbing. Compare the byId handler before and after:

1
// Before (Lessons 4-6): the controller handled "not found"
2
@GetMapping("/{id}")
3
public ResponseEntity<BookResponse> byId(@PathVariable UUID id) {
4
    return books.findById(id)
5
        .map(BookResponse::from)
6
        .map(ResponseEntity::ok)
7
        .orElse(ResponseEntity.notFound().build());
8
}
9

10
// After: the service throws, the global handler answers. The controller just maps.
11
@GetMapping("/{id}")
12
public BookResponse byId(@PathVariable UUID id) {
13
    return BookResponse.from(books.getById(id));
14
}

replace collapses the same way. Its return type drops from ResponseEntity<BookResponse> to BookResponse, the .map().orElse(...) chain disappears, and it keeps the @Valid you added to its body in Step 3:


32 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
7
import org.springframework.http.ResponseEntity;
8
import org.springframework.web.bind.annotation.DeleteMapping;
9
import org.springframework.web.bind.annotation.GetMapping;
10
import org.springframework.web.bind.annotation.PathVariable;
11
import org.springframework.web.bind.annotation.PostMapping;
12
import org.springframework.web.bind.annotation.PutMapping;
13
import org.springframework.web.bind.annotation.RequestBody;
14
import org.springframework.web.bind.annotation.RequestMapping;
15
import org.springframework.web.bind.annotation.RequestParam;
16
import org.springframework.web.bind.annotation.RestController;
17

18
@RestController
19
@RequestMapping("/api/books")
20
public class BookController {
21

22
    private final BookService books;
23

24
    public BookController(BookService books) {
25
        this.books = books;
26
    }
27

28
    @GetMapping                                          // GET /api/books  or  ?authorId=...
29
    public List<BookResponse> all(@RequestParam(required = false) UUID authorId) {
30
        return books.findAll(authorId).stream().map(BookResponse::from).toList();
31
    }
32

33
    @GetMapping("/{id}")
34
    public BookResponse byId(@PathVariable UUID id) {
35
        return BookResponse.from(books.getById(id));
36
    }
8 collapsed lines
37

38
    @PostMapping                                         // POST /api/books
39
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
40
        Book saved = books.create(req.title(), req.year(), req.authorIds());
41
        URI location = URI.create("/api/books/" + saved.getId());
42
        return ResponseEntity.created(location).body(BookResponse.from(saved));
43
    }
44

45
    @PutMapping("/{id}")
46
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
47
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
48
    }
7 collapsed lines
49

50
    @DeleteMapping("/{id}")                     // DELETE /api/books/{id}
51
    public ResponseEntity<Void> delete(@PathVariable UUID id) {
52
        return books.delete(id)
53
                ? ResponseEntity.noContent().build()
54
                : ResponseEntity.notFound().build();
55
    }
56
}

Delete becomes equally direct — no body, so declare the success status and let a missing id throw:


49 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
7
import org.springframework.http.ResponseEntity;
8
import org.springframework.web.bind.annotation.DeleteMapping;
9
import org.springframework.web.bind.annotation.GetMapping;
10
import org.springframework.web.bind.annotation.PathVariable;
11
import org.springframework.web.bind.annotation.PostMapping;
12
import org.springframework.web.bind.annotation.PutMapping;
13
import org.springframework.web.bind.annotation.RequestBody;
14
import org.springframework.web.bind.annotation.RequestMapping;
15
import org.springframework.web.bind.annotation.RequestParam;
16
import org.springframework.web.bind.annotation.RestController;
17

18
@RestController
19
@RequestMapping("/api/books")
20
public class BookController {
21

22
    private final BookService books;
23

24
    public BookController(BookService books) {
25
        this.books = books;
26
    }
27

28
    @GetMapping                                          // GET /api/books  or  ?authorId=...
29
    public List<BookResponse> all(@RequestParam(required = false) UUID authorId) {
30
        return books.findAll(authorId).stream().map(BookResponse::from).toList();
31
    }
32

33
    @GetMapping("/{id}")
34
    public BookResponse byId(@PathVariable UUID id) {
35
        return BookResponse.from(books.getById(id));
36
    }
37

38
    @PostMapping                                         // POST /api/books
39
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
40
        Book saved = books.create(req.title(), req.year(), req.authorIds());
41
        URI location = URI.create("/api/books/" + saved.getId());
42
        return ResponseEntity.created(location).body(BookResponse.from(saved));
43
    }
44

45
    @PutMapping("/{id}")
46
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
47
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
48
    }
49

50
    @DeleteMapping("/{id}")
51
    @ResponseStatus(HttpStatus.NO_CONTENT)     // 204 on success
52
    public void delete(@PathVariable UUID id) {
53
        books.delete(id);                      // throws NotFoundException -> 404
54
    }
55
}

That delete needs two imports the file didn't have before; ResponseEntity stays, because create still returns a 201 with a Location header:


6 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
7
import org.springframework.http.HttpStatus;
9 collapsed lines
8
import org.springframework.http.ResponseEntity;
9
import org.springframework.web.bind.annotation.DeleteMapping;
10
import org.springframework.web.bind.annotation.GetMapping;
11
import org.springframework.web.bind.annotation.PathVariable;
12
import org.springframework.web.bind.annotation.PostMapping;
13
import org.springframework.web.bind.annotation.PutMapping;
14
import org.springframework.web.bind.annotation.RequestBody;
15
import org.springframework.web.bind.annotation.RequestMapping;
16
import org.springframework.web.bind.annotation.RequestParam;
17
import org.springframework.web.bind.annotation.ResponseStatus;
39 collapsed lines
18
import org.springframework.web.bind.annotation.RestController;
19

20
@RestController
21
@RequestMapping("/api/books")
22
public class BookController {
23

24
    private final BookService books;
25

26
    public BookController(BookService books) {
27
        this.books = books;
28
    }
29

30
    @GetMapping                                          // GET /api/books  or  ?authorId=...
31
    public List<BookResponse> all(@RequestParam(required = false) UUID authorId) {
32
        return books.findAll(authorId).stream().map(BookResponse::from).toList();
33
    }
34

35
    @GetMapping("/{id}")
36
    public BookResponse byId(@PathVariable UUID id) {
37
        return BookResponse.from(books.getById(id));
38
    }
39

40
    @PostMapping                                         // POST /api/books
41
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
42
        Book saved = books.create(req.title(), req.year(), req.authorIds());
43
        URI location = URI.create("/api/books/" + saved.getId());
44
        return ResponseEntity.created(location).body(BookResponse.from(saved));
45
    }
46

47
    @PutMapping("/{id}")
48
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
49
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
50
    }
51

52
    @DeleteMapping("/{id}")
53
    @ResponseStatus(HttpStatus.NO_CONTENT)     // 204 on success
54
    public void delete(@PathVariable UUID id) {
55
        books.delete(id);                      // throws NotFoundException -> 404
56
    }
57
}

The author controller thins out the same way — it keeps both @Valids from Step 3, returns DTOs directly, and has a delete that can now end in three different statuses without a single branch in the controller:

1
package com.example.library.author;
2

3
import java.net.URI;
4
import java.util.List;
5
import java.util.UUID;
6
import jakarta.validation.Valid;
7
import org.springframework.http.HttpStatus;
8
import org.springframework.http.ResponseEntity;
9
import org.springframework.web.bind.annotation.DeleteMapping;
10
import org.springframework.web.bind.annotation.GetMapping;
11
import org.springframework.web.bind.annotation.PathVariable;
12
import org.springframework.web.bind.annotation.PostMapping;
13
import org.springframework.web.bind.annotation.PutMapping;
14
import org.springframework.web.bind.annotation.RequestBody;
15
import org.springframework.web.bind.annotation.RequestMapping;
16
import org.springframework.web.bind.annotation.ResponseStatus;
17
import org.springframework.web.bind.annotation.RestController;
18

19
@RestController
20
@RequestMapping("/api/authors")
21
public class AuthorController {
22

23
    private final AuthorService authors;
24

25
    public AuthorController(AuthorService authors) {
26
        this.authors = authors;
27
    }
28

29
    @GetMapping
30
    public List<AuthorResponse> all() {
31
        return authors.findAll().stream().map(AuthorResponse::from).toList();
32
    }
33

34
    @GetMapping("/{id}")
35
    public AuthorResponse byId(@PathVariable UUID id) {
36
        return AuthorResponse.from(authors.getById(id));
37
    }
38

39
    @PostMapping
40
    public ResponseEntity<AuthorResponse> create(@Valid @RequestBody CreateAuthorRequest req) {
41
        Author saved = authors.create(req.name());
42
        URI location = URI.create("/api/authors/" + saved.getId());
43
        return ResponseEntity.created(location).body(AuthorResponse.from(saved));
44
    }
45

46
    @PutMapping("/{id}")
47
    public AuthorResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateAuthorRequest req) {
48
        return AuthorResponse.from(authors.replace(id, req.name()));
49
    }
50

51
    @DeleteMapping("/{id}")
52
    @ResponseStatus(HttpStatus.NO_CONTENT)               // 204 on success
53
    public void delete(@PathVariable UUID id) {
54
        authors.delete(id);                              // NotFoundException -> 404, ConflictException -> 409
55
    }
56
}

The same pairing holds: once AuthorService.getById throws, byId must shed its Optional chain or it won't compile.

The payoff from Lesson 4's aside

Back in Lesson 4 we noted the Optional-in-the-controller pattern was a stepping stone, and that the production approach is "throw + one global handler." This is that step. Every controller method is now a thin translator with no error branches; the not-found logic exists once, in the service; the response formatting exists once, in the advice. One concern, one place — three times over.

Step 7 — Run it and watch the errors

Restart the app and probe the failure paths. Each one now comes back as application/problem+json:

# Blank title, negative year, missing authorIds -> 400 with a field map
curl -s -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{"title":"  ","year":-5}'

{
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "instance": "/api/books",
  "errors": {
    "title": "must not be blank",
    "year": "must be greater than 0",
    "authorIds": "must not be empty"
  }
}

# Unknown book id -> 404 problem+json
curl -s http://localhost:8080/api/books/00000000-0000-0000-0000-000000000000

{
  "title": "Resource not found",
  "status": 404,
  "detail": "No book with id 00000000-0000-0000-0000-000000000000",
  "instance": "/api/books/00000000-0000-0000-0000-000000000000"
}

# Valid fields but one authorIds entry matches no author -> 404 (no more 500!)
curl -s -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Refactoring","year":2018,"authorIds":["<existing-author-id>","00000000-0000-0000-0000-000000000000"]}'

{
  "title": "Resource not found",
  "status": 404,
  "detail": "No author with id [00000000-0000-0000-0000-000000000000]",
  "instance": "/api/books"
}

# Delete an author who still has a book (David Thomas's id, from GET /api/authors) -> 409 (no more 500!)
curl -s -X DELETE http://localhost:8080/api/authors/01a0c863-2be1-77cd-8cba-b8492f994901

{
  "title": "Conflict",
  "status": 409,
  "detail": "Author 01a0c863-2be1-77cd-8cba-b8492f994901 still has books; delete or re-author them first",
  "instance": "/api/authors/01a0c863-2be1-77cd-8cba-b8492f994901"
}

He's still there afterwards, and this time nothing reached the database: the service refused before the foreign key had to. Delete an author with no books and you get the quiet 204; name an id that doesn't exist and it's the 404 above.

And the failures you never wrote a line for — handled by the inherited base class — come back in the very same shape:

# Path id that isn't a UUID -> 400 (type mismatch)
curl -s http://localhost:8080/api/books/not-a-uuid
# Wrong method on a real route -> 405
curl -s -X PATCH http://localhost:8080/api/books/<some-id>
# Wrong Content-Type -> 415
curl -s -X POST http://localhost:8080/api/books -H "Content-Type: text/plain" -d 'hi'

// GET /api/books/not-a-uuid
{ "title": "Bad Request", "status": 400,
  "detail": "Failed to convert 'id' with value: 'not-a-uuid'", "instance": "/api/books/not-a-uuid" }

// PATCH ...   -> { "title": "Method Not Allowed",     "status": 405, "detail": "Method 'PATCH' is not supported." }
// text/plain  -> { "title": "Unsupported Media Type", "status": 415, "detail": "Content-Type 'text/plain;charset=UTF-8' is not supported." }

And anything truly unforeseen — say a title too long for its column — trips the catch-all: a generic 500 to the client, with the real cause logged server-side and never sent out.

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred.",
  "instance": "/api/books"
}

Every failure now leaves the API in one consistent application/problem+json shape with the right status — your validation (400), not-found (404) and conflict (409), the framework's 4xx, and the unforeseen 500. That uniformity is what makes an API pleasant to consume.

If it doesn't behave

Bad input returns 200/201 instead of 400? A constraint annotation with no @Valid at the @RequestBody, or the validation starter isn't on the classpath. Both are required.
Validation fails but the body is Spring's default, not your Problem Detail? The advice isn't being found — make sure ApiExceptionHandler is under com.example.library so component scanning picks it up, and that it's annotated @RestControllerAdvice.
Still getting a 500 for a bad authorIds entry? requireAuthors is throwing something other than NotFoundException (e.g. the old NoSuchElementException), so no handler matches. Throw the domain exception.
@NotNull on year does nothing? int is a primitive — it can't be null. Use @Positive/@Min for numbers; use @NotEmpty for a collection like Set<UUID> authorIds, since @NotNull alone wouldn't catch an empty set.

Check yourself

Answer from memory before revealing.

A CreateBookRequest field has @NotBlank, but blank titles still get through. What's the most likely cause?

What does a single @RestControllerAdvice give your API?

After the refactor, what happens in byId when the book id is unknown?

Why does @NotNull on an int year field accomplish nothing?

Read this next

Primary source: Baeldung's Error Handling for REST with Spring — the canonical walkthrough of @RestControllerAdvice, @ExceptionHandler, and ProblemDetail. Pair it with Validation in Spring Boot for the constraint side. For the standard your errors now follow, skim RFC 9457 (Problem Details for HTTP APIs).

Glossary: the terms this lesson introduces are in the Glossary, under Lesson 7 — your quick-reference for every term we use.

Architecture decisions: the 8 choices this lesson makes, each with its reason, are in Architecture Decisions, under Lesson 7.

Code: the project at the end of this lesson · what changed in this lesson, exercises included.

💬 Discuss