Handling not found exceptions in Spring Boot - Mini Project: Build & Apply

Handling not found exceptions in Spring Boot

📖 Scenario: You are building a simple Spring Boot REST API for managing books in a library. Users can request details of a book by its ID.Sometimes, the requested book ID does not exist in the system. You want to handle this case gracefully by sending a clear error message and a proper HTTP status code.

🎯 Goal: Build a Spring Boot REST controller that returns book details by ID. If the book is not found, return a 404 Not Found response with a custom error message.

📋 What You'll Learn

Create a simple data structure to hold book information

Add a configuration variable for the error message

Implement a method to find a book by ID and throw a custom exception if not found

Create an exception handler to return a 404 status and error message

💡 Why This Matters

🌍 Real World

Handling not found exceptions is common in web APIs to inform clients clearly when requested data does not exist.

💼 Career

Backend developers often implement exception handling in Spring Boot to improve API reliability and user experience.

1

Create the initial book data structure

Create a Map<Integer, String> called books with these exact entries: 1 mapped to "Spring Boot Basics", 2 mapped to "Java Fundamentals", and 3 mapped to "REST API Design".

Spring Boot

// Create the books map with IDs and titles
// Your code here

Hint

Use Map.of() to create an immutable map with the given entries.

2

Add a custom error message variable

Create a String variable called notFoundMessage and set it to "Book not found".

Spring Boot

Map books = Map.of(
    1, "Spring Boot Basics",
    2, "Java Fundamentals",
    3, "REST API Design"
);

// Create the notFoundMessage variable
// Your code here

Hint

Just create a simple String variable with the exact name and value.

3

Implement method to find book or throw exception

Write a method called getBookById that takes an int id parameter and returns a String. Inside, use books.get(id) to get the book title. If the result is null, throw a new BookNotFoundException with notFoundMessage. Otherwise, return the book title.

Spring Boot

Map books = Map.of(
    1, "Spring Boot Basics",
    2, "Java Fundamentals",
    3, "REST API Design"
);

String notFoundMessage = "Book not found";

// Write getBookById method below
// Your code here

Hint

Check if the book is null and throw the exception with the message variable.

4

Create exception handler for BookNotFoundException

Add a method annotated with @ExceptionHandler(BookNotFoundException.class) that returns a ResponseEntity<String>. The method should take a BookNotFoundException ex parameter and return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage()).

Spring Boot

Map books = Map.of(
    1, "Spring Boot Basics",
    2, "Java Fundamentals",
    3, "REST API Design"
);

String notFoundMessage = "Book not found";

public String getBookById(int id) {
    String book = books.get(id);
    if (book == null) {
        throw new BookNotFoundException(notFoundMessage);
    }
    return book;
}

// Add exception handler method below
// Your code here

Hint

Use @ExceptionHandler annotation and return a ResponseEntity with 404 status and the exception message.

Practice

1. What is the main purpose of handling not found exceptions in a Spring Boot application?

easy

A. To improve database performance

B. To log all user activities

C. To automatically retry failed requests

D. To return a clear 404 status when a requested resource is missing

Solution

1. Step 1: Understand the role of not found exceptions

   Not found exceptions indicate that a requested resource does not exist on the server.

2. Step 2: Identify the correct response behavior

   Returning a 404 HTTP status code clearly informs the client that the resource is missing.

3. Final Answer:

   To return a clear 404 status when a requested resource is missing -> Option D

4. Quick Check:

   Not found exceptions = 404 status [OK]

Hint: Not found means resource missing, so send 404 status [OK]

Common Mistakes:

• Confusing not found with server errors
• Thinking it improves database speed
• Assuming it retries requests automatically

2. Which annotation is used in Spring Boot to mark a custom exception class to return HTTP 404 status automatically?

easy

A. @ResponseStatus(HttpStatus.NOT_FOUND)

B. @ExceptionHandler(HttpStatus.NOT_FOUND)

C. @NotFoundException

D. @HttpStatusCode(404)

Solution

1. Step 1: Recall Spring Boot annotations for HTTP status

   The @ResponseStatus annotation sets the HTTP status code for exceptions or controller methods.

2. Step 2: Match the annotation to 404 status

   Using @ResponseStatus(HttpStatus.NOT_FOUND) on a custom exception class sends 404 automatically.

3. Final Answer:

   @ResponseStatus(HttpStatus.NOT_FOUND) -> Option A

4. Quick Check:

   @ResponseStatus + NOT_FOUND = 404 [OK]

Hint: Use @ResponseStatus with NOT_FOUND for 404 exceptions [OK]

Common Mistakes:

• Using @ExceptionHandler instead of @ResponseStatus
• Assuming @NotFoundException is a valid annotation
• Using incorrect annotation names

3. Given this controller method in Spring Boot:

 @GetMapping("/items/{id}")
 public Item getItem(@PathVariable Long id) {
     return itemRepository.findById(id)
         .orElseThrow(() -> new ItemNotFoundException(id));
 }

What happens if the item with the given id does not exist?

medium

A. The method returns null and HTTP 200 status

B. An ItemNotFoundException is thrown and HTTP 404 status is returned

C. The server crashes with a NullPointerException

D. The method returns an empty Item object

Solution

1. Step 1: Analyze the use of orElseThrow

   If the item is not found, orElseThrow triggers the custom ItemNotFoundException.

2. Step 2: Understand exception handling with @ResponseStatus

   If ItemNotFoundException is annotated with @ResponseStatus(HttpStatus.NOT_FOUND), Spring returns 404 status.

3. Final Answer:

   An ItemNotFoundException is thrown and HTTP 404 status is returned -> Option B

4. Quick Check:

   orElseThrow + @ResponseStatus = 404 error [OK]

Hint: orElseThrow triggers exception, annotated exception sends 404 [OK]

Common Mistakes:

• Assuming null is returned instead of exception
• Confusing 404 with 500 server error
• Thinking empty object is returned

4. Consider this code snippet:

 @ResponseStatus(HttpStatus.NOT_FOUND)
 public class ProductNotFoundException extends RuntimeException {
     public ProductNotFoundException(Long id) {
         super("Product " + id + " not found");
     }
 }

 @GetMapping("/products/{id}")
 public Product getProduct(@PathVariable Long id) {
     return productRepo.findById(id).orElseThrow(() -> new ProductNotFoundException(id));
 }

What is the likely problem if the client always receives HTTP 500 instead of 404 when a product is missing?

medium

A. The exception is thrown but Spring does not map it to 404

B. The exception is not annotated with @ResponseStatus

C. The controller method does not handle the exception explicitly

D. The exception class is missing a no-argument constructor

Solution

1. Step 1: Verify annotation presence

   The exception class is correctly annotated with @ResponseStatus(HttpStatus.NOT_FOUND).

2. Step 2: Understand Spring's exception mapping

   If Spring returns 500, it means it does not recognize the exception mapping to 404, possibly due to package scanning or configuration issues.

3. Final Answer:

   The exception is thrown but Spring does not map it to 404 -> Option A

4. Quick Check:

   Annotated exception but 500 means mapping failed [OK]

Hint: 500 instead of 404 means Spring missed exception mapping [OK]

Common Mistakes:

• Assuming missing no-arg constructor causes 500
• Thinking @ResponseStatus is missing when it is present
• Believing explicit handler is always required

5. You want to create a global exception handler in Spring Boot that returns a JSON error with 404 status and a message when any ResourceNotFoundException occurs. Which approach correctly achieves this?

hard

A. Use @RestController on the exception class and return 404 status

B. Annotate ResourceNotFoundException with @ResponseStatus(HttpStatus.NOT_FOUND) only, no handler needed

C. Create a class annotated with @ControllerAdvice and a method with @ExceptionHandler(ResourceNotFoundException.class) returning ResponseEntity with status 404 and error body

D. Throw ResponseStatusException with 404 inside every controller method manually

Solution

1. Step 1: Understand global exception handling

   Using @ControllerAdvice with @ExceptionHandler allows centralized handling of exceptions across controllers.

2. Step 2: Return ResponseEntity with 404 and JSON body

   The handler method can build a ResponseEntity with HttpStatus.NOT_FOUND and a JSON error message for clients.

3. Final Answer:

   Create a class annotated with @ControllerAdvice and a method with @ExceptionHandler(ResourceNotFoundException.class) returning ResponseEntity with status 404 and error body -> Option C

4. Quick Check:

   Global handler + ResponseEntity = custom 404 JSON [OK]

Hint: Use @ControllerAdvice + @ExceptionHandler for global JSON 404 [OK]

Common Mistakes:

• Relying only on @ResponseStatus without custom JSON body
• Annotating exception class as controller
• Manually throwing exceptions in every method