Exception Handling in Spring Boot using @ControllerAdvice

-

Introduction :

When developing REST APIs, errors can occur for many reasons. For example, a user may request data that does not exist, submit invalid information, or encounter an unexpected server issue.

If exceptions are not handled properly, the application may return confusing error messages to the client.

Spring Boot provides a powerful mechanism to handle exceptions globally using @ControllerAdvice and @ExceptionHandler.

In this tutorial, we will learn how to:

✅ Create a Custom Exception

✅ Implement Global Exception Handling

✅ Use @ControllerAdvice

✅ Use @ExceptionHandler

✅ Return meaningful error responses to API consumers

Why Do We Need Exception Handling?

Consider the following API:

@GetMapping("/{id}")
public Employee getEmployeeById(@PathVariable Long id) {
    return employeeRepository.findById(id)
            .orElseThrow(() -> new RuntimeException("Employee not found"));
}

If the employee does not exist, Spring Boot returns a generic error response.

Instead of showing technical errors to users, we should return a clear and meaningful message.

Example:

{
    "message": "Employee not found with ID: 10"
}

This improves the API experience and makes debugging easier.

Step 1: Create Custom Exception

Create a class named ResourceNotFoundException.java

public class ResourceNotFoundException extends RuntimeException {

    public ResourceNotFoundException(String message) {
        super(message);
    }

}

This exception will be used whenever a requested resource is not found.

Step 2: Use Custom Exception in Service Layer

Update the service method:

public Employee getEmployeeById(Long id) {

    return employeeRepository.findById(id)
            .orElseThrow(() ->
                    new ResourceNotFoundException(
                            "Employee not found with ID: " + id));

}

Now, instead of throwing a generic exception, we throw a custom exception.

Step 3: Create Global Exception Handler

Create a class named GlobalExceptionHandler.java

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleResourceNotFoundException(
            ResourceNotFoundException ex) {

        return new ResponseEntity<>(
                ex.getMessage(),
                HttpStatus.NOT_FOUND);

    }

}

Explanation

@ControllerAdvice

Allows handling exceptions globally across the application.

@ExceptionHandler

Handles specific exception types and returns custom responses.

Step 4: Test the API

Suppose Employee ID 100 does not exist.

Request:

GET /employees/100

Response:

Employee not found with ID: 100

HTTP Status:

404 NOT FOUND

This response is much cleaner and easier for API consumers to understand.

Benefits of Global Exception Handling

  • Centralized exception management

  • Cleaner controller code

  • Consistent API responses

  • Better user experience

  • Easier maintenance

Common Interview Questions

What is @ControllerAdvice?

@ControllerAdvice is used to handle exceptions globally across multiple controllers in a Spring Boot application.

What is @ExceptionHandler?

@ExceptionHandler is used to handle specific exceptions and return custom responses.

Why create custom exceptions?

Custom exceptions provide meaningful error messages and make application logic easier to understand and maintain.

Conclusion :

In this tutorial, we learned how to implement exception handling in Spring Boot using @ControllerAdvice and @ExceptionHandler.

We created:

✅ Custom Exception

✅ Global Exception Handler

✅ Meaningful Error Responses

Exception handling is an important part of building production-ready REST APIs and is commonly used in real-world Spring Boot applications.

In the next tutorial, we will learn how to implement Pagination and Sorting in Spring Boot.

Comments

Post a Comment

Popular posts from this blog

React Basics – How to Create Component

-
  Introduction (Story) : When I started learning React, I was confused about how components actually work. I saw many examples, but things became clear only when I created my own first component. In this blog, I will explain how to create a simple React component step by step in an easy way. What is a Component in React? A component is a reusable piece of UI in React. It helps in breaking the application into smaller, manageable parts. Tools Required : Node.js React (Create React App / Vite) VS Code  Step 1: Create React App : Run the following command: Where you want create the react project, then we have to create new folder and there you can open the cmd and run below command npx create-react-app my-app Navigate to project folder: cd my-app npm start Step 2: Create Your First Component Create a file named Hello.js import React from 'react' ; function Hello () { return <h1> Hello, Welcome to React! </h1> ; } export default Hello ; Step 3: ...
Read more

How to Build REST API using Spring Boot (Step-by-Step Guide)

-
Introduction  (Story + Experience)  : When I started learning Spring Boot, I found REST APIs a bit confusing. I watched multiple tutorials, but I didn’t fully understand how backend systems actually work. Things became clear when I tried building a simple REST API on my own. In this blog, I will share the same step-by-step process that helped me understand REST APIs in a practical way. What is REST API? A REST API allows communication between frontend and backend systems using HTTP methods like GET, POST, PUT, and DELETE. In real-world applications, REST APIs are used to send and receive data between client and server. Tools Required  : - Java - Spring Boot - IntelliJ / VS Code - Postman Step 1: Create Spring Boot Project  : Go to Spring Initializr and create a project with the following dependencies: - Spring Web - Spring Data JPA - PostgreSQL Driver Step 2: Create Controller  : @RestController @RequestMapping("/api") public class HelloController {   ...
Read more

Spring Boot @RequestParam Annotation Explained with Real-Time Examples

-
Image
 Introduction : As a Java Full Stack Developer, I have worked on several Spring Boot applications where APIs needed to receive data from users. One annotation that I frequently used in REST APIs is @RequestParam . In many real-world applications, users need to search, filter, sort, or paginate data. For example, an employee management system may allow users to search employees by department, status, or employee ID. In such cases, @RequestParam provides a simple and efficient way to pass data from the client to the server through URL query parameters. When I started learning Spring Boot, I often got confused between @RequestParam , @PathVariable , and @RequestBody . However, after working on multiple projects, I understood the purpose of each annotation and when to use them effectively. In this article, I will explain the @RequestParam annotation with practical examples, project use cases, common mistakes, best practices, and interview questions. What is @RequestParam? The @Reques...
Read more