@ExceptionHandler (Controller-Level Exception Handling)

@ExceptionHandler is a Spring annotation used to handle exceptions at the controller level. Instead of letting an application crash or return generic error responses, it allows you to catch exceptions and return meaningful, structured messages to clients.

It is especially useful in REST APIs for providing clean and consistent error responses.

What is @ExceptionHandler?

@ExceptionHandler is a controller-level exception handler in Spring Boot:

• Captures specific exceptions thrown in controller methods
• Returns custom responses (JSON, text, HTTP status codes)
• Prevents Spring Boot from returning default HTML error pages
• Allows full control over HTTP status codes and error messages

Simple Definition:

A Spring annotation used to handle exceptions thrown by controller methods without using try-catch blocks.

Basic Example

@RestController
@RequestMapping("/users")
publicclassUserController {

@GetMapping("/{id}")
public UsergetUser(@PathVariableint id) {
return userService.findById(id);// may throw UserNotFoundException
    }

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<String>handleUserNotFound(UserNotFoundException ex) {
return ResponseEntity
                .status(HttpStatus.NOT_FOUND)
                .body(ex.getMessage());
    }
}

Outcome:

• User exists → API returns user data
• User not found → API returns 404 Not Found with a clear message

Why Use @ExceptionHandler?

Benefits of using @ExceptionHandler:

• Avoid repeated try-catch blocks
• Keep business logic separate from error handling
• Return meaningful, structured error messages
• Improve REST API quality and readability

How @ExceptionHandler Works

1. Controller method throws an exception
2. Spring searches for a matching @ExceptionHandler method within the same controller
3. Exception is caught by the handler method
4. Custom response is sent to the client

Flow Diagram:

User Request → ControllerMethod Executes
        ↓
UserNotFoundException Thrown?
        ↓
Yes → @ExceptionHandler CapturesException
        ↓
Return Custom Response (e.g.,404NotFound)

Handling Multiple Exceptions

You can handle more than one exception in a single handler:

@ExceptionHandler({UserNotFoundException.class, OrderNotFoundException.class})
public ResponseEntity<String>handleNotFoundExceptions(RuntimeException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND)
                         .body(ex.getMessage());
}

Returning Structured JSON Responses

REST APIs work better with structured JSON errors instead of plain text:

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse>handleUserNotFound(UserNotFoundException ex) {
ErrorResponseerror=newErrorResponse(
            ex.getMessage(),
            HttpStatus.NOT_FOUND.value(),
            System.currentTimeMillis()
    );
returnnewResponseEntity<>(error, HttpStatus.NOT_FOUND);
}

ErrorResponse Class:

publicclassErrorResponse {
private String message;
privateint status;
privatelong timestamp;

publicErrorResponse(String message, int status,long timestamp) {
this.message = message;
this.status = status;
this.timestamp = timestamp;
    }

// getters and setters
}

Example JSON Response:

{
"message":"User not found",
"status":404,
"timestamp":1672567890123
}

Scope of @ExceptionHandler in Spring Boot

@ExceptionHandler works at the controller level, which means it only handles exceptions inside the controller where it is defined.

Limitations

• Works only for one controller
• Cannot handle global exceptions across multiple controllers
• Repeated logic if multiple controllers need similar handling
• Less suitable for large apps or microservices

For global exception handling, use @ControllerAdvice or @RestControllerAdvice

@ExceptionHandler vs Try-Catch

When handling exceptions in Spring Boot, you can use Try-Catch or @ExceptionHandler.

Understanding the differences helps you choose the right approach for your project.

When to Use @ExceptionHandler

@ExceptionHandler is a controller-level exception handling approach, which means it works only within the controller where it is defined.

Knowing when to use it ensures clean, maintainable, and professional REST APIs.

Best Use Cases:

Use @ExceptionHandler when:

• You have a single-controller application
• Your project is small to medium-sized
• Exception handling logic differs between controllers
• You want to keep controller methods clean without repetitive try-catch blocks

Example: A small user management API with just one UserController.

Avoid Using @ExceptionHandler When

Do not rely on @ExceptionHandler if:

• You have multiple controllers in your application
• You need centralized/global exception handling
• You want to reuse exception handling logic across different controllers
• Your application is large or microservice-based

In these cases, prefer @RestControllerAdvice or @ControllerAdvice, which provide global and reusable exception handling.

Conclusion

@ExceptionHandler is a controller-level exception handling solution in Spring Boot:

• Keeps controllers clean and readable
• Returns custom, meaningful responses
• Avoids repetitive try-catch code

Limitations: Works only for single controllers. For large applications, use:

• @ControllerAdvice → Global exception handling for all controllers
• @RestControllerAdvice → REST-friendly global exception handling