keping jiang

Posted on Aug 16

How I Handle Global Exception Handling in a Spring Boot Application

#architecture #java #springboot

How I Handle Global Exception Handling in a Spring Boot Application

Exception handling is one of those things that often starts simple and gradually becomes messy.

At the beginning of a Spring Boot application, it is common to see code like this:

try {
    userService.createUser(request);
} catch (Exception e) {
    return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body("Something went wrong");
}

This might work for a small application.

But as the application grows, repeating exception handling logic across controllers quickly becomes difficult to maintain.

In this article, I want to share a simple approach I use to structure global exception handling in a Spring Boot application.

The goals are straightforward:

Keep controllers clean
Return consistent API responses
Separate business errors from system errors
Make the application easier to maintain

The Problem with Handling Exceptions in Every Controller

Imagine an application with many endpoints.

Without centralized exception handling, you might end up with something like this:

@PostMapping("/users")
public ResponseEntity<?> createUser(
        @RequestBody CreateUserRequest request) {

    try {

        User user = userService.createUser(request);

        return ResponseEntity.ok(user);

    } catch (UserAlreadyExistsException e) {

        return ResponseEntity
                .status(HttpStatus.CONFLICT)
                .body(e.getMessage());

    } catch (Exception e) {

        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Internal server error");
    }
}

Then another controller might contain similar code.

And another.

Over time, this creates several problems:

Repeated code
Inconsistent error responses
Controllers become harder to read
Exception logic becomes scattered across the application

I prefer to move this responsibility into one centralized place.

1. Start with Custom Exceptions

The first step is to distinguish between different types of errors.

For example:

public class ResourceNotFoundException
        extends RuntimeException {

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

Another example:

public class BusinessException
        extends RuntimeException {

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

For duplicate resources:

public class ResourceAlreadyExistsException
        extends RuntimeException {

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

These exceptions make the business logic easier to understand.

For example:

public User findById(Long id) {

    return userRepository
            .findById(id)
            .orElseThrow(() ->
                    new ResourceNotFoundException(
                            "User not found"
                    )
            );
}

The service does not need to know anything about HTTP responses.

It simply expresses what went wrong.

2. Create a Consistent Error Response

One thing I strongly recommend is using a consistent error response format.

For example:

{
  "timestamp": "2026-08-15T10:30:00",
  "status": 404,
  "error": "NOT_FOUND",
  "message": "User not found",
  "path": "/api/users/123"
}

We can represent this with a simple class:

public class ErrorResponse {

    private LocalDateTime timestamp;

    private int status;

    private String error;

    private String message;

    private String path;

    // constructors
    // getters
}

Using one standard response format makes the API easier to consume.

Clients do not need to handle a completely different error structure for every endpoint.

3. Use @RestControllerAdvice

Spring provides a very useful mechanism for centralized exception handling:

@RestControllerAdvice
public class GlobalExceptionHandler {
}

Now we can define handlers for different exceptions.

For example:

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(
        ResourceNotFoundException ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.NOT_FOUND.value(),
            HttpStatus.NOT_FOUND.getReasonPhrase(),
            ex.getMessage(),
            request.getRequestURI()
    );

    return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(response);
}

Now whenever a ResourceNotFoundException is thrown anywhere in the application, Spring can handle it automatically.

The controller stays clean.

4. Handle Business Exceptions Separately

Not every exception is a system failure.

Sometimes an error is part of normal business behavior.

For example:

User already exists

Or:

Account is inactive

Or:

Document processing is not allowed

These can be handled separately.

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handleBusinessException(
        BusinessException ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.BAD_REQUEST.value(),
            HttpStatus.BAD_REQUEST.getReasonPhrase(),
            ex.getMessage(),
            request.getRequestURI()
    );

    return ResponseEntity
            .badRequest()
            .body(response);
}

This gives the client a predictable response.

5. Handle Validation Errors

Validation errors are another important case.

For example:

public class CreateUserRequest {

    @NotBlank
    private String username;

    @Email
    private String email;

    @NotBlank
    private String password;
}

When validation fails, Spring throws a validation exception.

We can handle it globally:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationException(
        MethodArgumentNotValidException ex,
        HttpServletRequest request) {

    String message = ex
            .getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error ->
                    error.getField()
                    + ": "
                    + error.getDefaultMessage()
            )
            .findFirst()
            .orElse("Validation failed");

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.BAD_REQUEST.value(),
            HttpStatus.BAD_REQUEST.getReasonPhrase(),
            message,
            request.getRequestURI()
    );

    return ResponseEntity
            .badRequest()
            .body(response);
}

For more complex APIs, you may want to return all validation errors instead of just the first one.

For example:

{
  "timestamp": "2026-08-15T10:30:00",
  "status": 400,
  "error": "BAD_REQUEST",
  "message": "Validation failed",
  "errors": {
    "username": "must not be blank",
    "email": "must be a valid email address"
  }
}

This can provide a better experience for frontend developers and API consumers.

6. Always Have a Fallback Exception Handler

Finally, I recommend having a handler for unexpected exceptions.

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(
        Exception ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(),
            "An unexpected error occurred",
            request.getRequestURI()
    );

    return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(response);
}

However, there is an important detail here.

I generally do not return the full exception message to the client.

For example, this is usually not a good idea:

.body(ex.getMessage());

Unexpected exceptions may contain implementation details or sensitive information.

Instead:

Client receives:
An unexpected error occurred

While the actual exception should be logged internally.

For example:

log.error("Unexpected error", ex);

This keeps internal implementation details away from API clients while still making debugging possible.

7. Keep Controllers Focused on HTTP Requests

With global exception handling in place, controllers become much simpler.

Instead of this:

@PostMapping("/users")
public ResponseEntity<?> createUser(
        @RequestBody CreateUserRequest request) {

    try {

        User user = userService.createUser(request);

        return ResponseEntity.ok(user);

    } catch (Exception e) {

        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Something went wrong");
    }
}

We can write:

@PostMapping("/users")
public ResponseEntity<User> createUser(
        @Valid @RequestBody CreateUserRequest request) {

    User user = userService.createUser(request);

    return ResponseEntity.ok(user);
}

The controller focuses on:

HTTP Request
        ↓
Validation
        ↓
Service
        ↓
HTTP Response

Exception handling happens separately.

This makes the application easier to read and maintain.

8. My Basic Exception Structure

For a typical Spring Boot application, I like to keep the structure simple:

exception
├── BusinessException
├── ResourceNotFoundException
├── ResourceAlreadyExistsException
└── GlobalExceptionHandler

As the application grows, additional exception types can be added when they represent meaningful business concepts.

The important thing is not to create dozens of exception classes unnecessarily.

Start with a small set:

Not Found
Conflict
Business Error
Validation Error
Unexpected Error

That is often enough for many applications.

A Simple Mental Model

I think about exceptions in three categories:

Business Errors
        ↓
Expected application behavior

Validation Errors
        ↓
Invalid client input

System Errors
        ↓
Unexpected failures

Each category should have a predictable API response.

For example:

Error Type	HTTP Status
Resource not found	404
Invalid request	400
Resource already exists	409
Unauthorized	401
Forbidden	403
Unexpected error	500

The exact structure may vary depending on the application, but consistency is important.

Final Thoughts

Global exception handling is not one of the most exciting parts of a Spring Boot application.

But it has a big impact on the overall quality of the API.

A good exception handling strategy should:

Keep controllers clean
Separate business logic from HTTP concerns
Return consistent error responses
Avoid exposing internal implementation details
Make the application easier to maintain

My preferred starting point is simple:

Custom Exceptions
        ↓
@RestControllerAdvice
        ↓
Consistent Error Response
        ↓
Structured Logging

You do not need a complicated exception framework to get started.

A small and consistent structure is usually enough.

As the application grows, you can evolve the error model based on real requirements.

How do you handle exceptions in your Spring Boot applications?

Do you use:

@RestControllerAdvice?
Custom business exceptions?
A standard API error response?
Problem Details / RFC 9457?

I'd love to hear how other Java developers structure exception handling in production applications.

I'm building and sharing open-source projects around Java, Spring Boot, enterprise application architecture, and AI-powered applications.

My goal is to explore practical patterns and reusable tools that help developers build enterprise applications faster.

DEV Community

How I Handle Global Exception Handling in a Spring Boot Application

How I Handle Global Exception Handling in a Spring Boot Application

The Problem with Handling Exceptions in Every Controller

1. Start with Custom Exceptions

2. Create a Consistent Error Response

3. Use @RestControllerAdvice

4. Handle Business Exceptions Separately

5. Handle Validation Errors

6. Always Have a Fallback Exception Handler

7. Keep Controllers Focused on HTTP Requests

8. My Basic Exception Structure

A Simple Mental Model

Final Thoughts

How do you handle exceptions in your Spring Boot applications?

Top comments (0)