@ExceptionHandler in controllers in Spring Boot - Mini Project: Build & Apply

Handling Errors in Spring Boot Controllers with @ExceptionHandler

📖 Scenario: You are building a simple Spring Boot web application that manages a list of books. Sometimes, users might request a book that does not exist. You want to handle such errors gracefully by showing a friendly error message instead of a server error.

🎯 Goal: Learn how to use @ExceptionHandler in a Spring Boot controller to catch exceptions and return a custom error response.

📋 What You'll Learn

Create a custom exception class called BookNotFoundException

Create a controller class called BookController with a method to get a book by its ID

Add a method in BookController annotated with @ExceptionHandler(BookNotFoundException.class) to handle the exception

Return a simple error message string from the exception handler method

💡 Why This Matters

🌍 Real World

Handling errors gracefully in web applications improves user experience by showing clear messages instead of confusing errors.

💼 Career

Knowing how to use @ExceptionHandler is essential for backend developers working with Spring Boot to build robust and user-friendly APIs.

1

Create the custom exception class

Create a public class called BookNotFoundException that extends RuntimeException. Add a constructor that accepts a String message and passes it to the superclass constructor.

Spring Boot

// Your code here

Need a hint?

Think of BookNotFoundException as a special error you create to say "This book was not found." It should extend RuntimeException so Spring can catch it easily.

2

Create the BookController with a sample data map

Create a class called BookController annotated with @RestController. Inside it, create a Map<Integer, String> called books initialized with these entries: 1: "Spring Boot Guide", 2: "Java Basics", 3: "REST API Design".

Spring Boot

public class BookNotFoundException extends RuntimeException {
    public BookNotFoundException(String message) {
        super(message);
    }
}

// Your code here

Need a hint?

Use @RestController to make this class a web controller. Use Map.of to create a simple fixed map of book IDs to titles.

3

Add a method to get a book by ID and throw exception if not found

Inside BookController, add a method getBookById annotated with @GetMapping("/books/{id}"). It takes an @PathVariable int id and returns the book title from books. If the book ID is not in the map, throw a new BookNotFoundException with message "Book not found with id: " + id.

Spring Boot

public class BookNotFoundException extends RuntimeException {
    public BookNotFoundException(String message) {
        super(message);
    }
}

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import java.util.Map;

@RestController
public class BookController {
    private Map books = Map.of(
        1, "Spring Boot Guide",
        2, "Java Basics",
        3, "REST API Design"
    );

    // Add getBookById method here
}

Need a hint?

Use @GetMapping to map the URL. Check if the book ID exists in the map. If not, throw your custom exception.

4

Add an @ExceptionHandler method to handle BookNotFoundException

Inside BookController, add a method annotated with @ExceptionHandler(BookNotFoundException.class). This method should take a BookNotFoundException parameter and return a String with the exception's message.

Spring Boot

public class BookNotFoundException extends RuntimeException {
    public BookNotFoundException(String message) {
        super(message);
    }
}

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import java.util.Map;

@RestController
public class BookController {
    private Map books = Map.of(
        1, "Spring Boot Guide",
        2, "Java Basics",
        3, "REST API Design"
    );

    @GetMapping("/books/{id}")
    public String getBookById(@PathVariable int id) {
        if (!books.containsKey(id)) {
            throw new BookNotFoundException("Book not found with id: " + id);
        }
        return books.get(id);
    }

    // Add exception handler method here
}

Need a hint?

The @ExceptionHandler method catches your custom exception and returns its message as a response. This way, users see a friendly message instead of an error page.