Spring Boot Exception Handling Annotations

If a handler returns a plain object, such as a Map or a record, Spring has no status to use, so it defaults to 200 OK. The client then believes the request succeeded.

Set the status in one of three ways:

// 1. @ResponseStatus on the method
@ExceptionHandler
@ResponseStatus(HttpStatus.CONFLICT)
public ErrorMessage handle(CourseFullException ex) { ... }

// 2. ResponseEntity
@ExceptionHandler
public ResponseEntity<ErrorMessage> handle(CourseFullException ex) {
    return ResponseEntity.status(HttpStatus.CONFLICT).body(...);
}

// 3. ProblemDetail, which carries its own status
@ExceptionHandler
public ProblemDetail handle(CourseFullException ex) {
    return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
}

Because a handler inside a controller is local: it only sees exceptions thrown by that controller’s own methods. This is by design, so one controller can treat an error differently from the rest of the application.

To share a handler, move it into a class annotated with @ControllerAdvice or @RestControllerAdvice.

The controller’s own handler always wins, even if the advice has a more specific match. Spring looks inside the controller first and only consults advice classes when the controller has no matching handler.

This lets you override the global behavior for one controller, for example returning a friendlier message for a public endpoint, without changing the shared advice.

When reason is set, Spring calls response.sendError(status, reason). The request then goes to Spring Boot’s standard error handling, and your exception message is not used:

@ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "Course not found")
public class CourseNotFoundException extends RuntimeException { ... }

• The reason text is fixed, so it cannot include details such as the course code.
• Even the reason is hidden from the JSON response unless server.error.include-message=always is set.

For dynamic messages, leave out reason and handle the exception with an @ExceptionHandler instead.

None. They are aliases for the same setting, so these two lines mean exactly the same:

@ResponseStatus(HttpStatus.NOT_FOUND)
@ResponseStatus(code = HttpStatus.NOT_FOUND)

value lets you write the shorter form when the status is the only attribute. Use code when you also set reason, because it reads more clearly. Setting both to different values causes an error.

Yes. Spring searches the class hierarchy for the annotation, so a subclass gets its parent’s status unless it declares its own:

@ResponseStatus(HttpStatus.NOT_FOUND)
public abstract class SchoolResourceNotFoundException extends RuntimeException { ... }

public class CourseNotFoundException extends SchoolResourceNotFoundException { ... }   // 404
public class StudentNotFoundException extends SchoolResourceNotFoundException { ... }  // 404

This is a tidy way to give a whole family of exceptions the same status code.

The @ExceptionHandler wins. Handlers are checked before the resolver that reads @ResponseStatus on exception classes, so the annotation on the class is ignored for that exception.

The response status then comes only from the handler. If the handler returns a plain object without its own @ResponseStatus, the result is 200, not the status written on the exception class.

No. Spring does not read handlers from top to bottom. It always picks the handler whose exception type is the closest match, wherever the method appears in the class.

What you must avoid is mapping the same exception type in two methods of one class. Spring cannot choose between them and fails with an “Ambiguous @ExceptionHandler method” error:

@ExceptionHandler(CourseFullException.class)
public ProblemDetail first(CourseFullException ex) { ... }

@ExceptionHandler(CourseFullException.class)   // error: same type mapped twice
public ProblemDetail second(CourseFullException ex) { ... }

Yes. Since Spring Framework 5.3, Spring checks the exception and then each of its causes, however deeply nested:

// Somewhere deep in the code:
throw new EnrollmentFailedException("Could not enroll", new CourseFullException("JAVA101", 30));

// This handler still matches, through the cause:
@ExceptionHandler
public ProblemDetail handleCourseFull(CourseFullException ex) { ... }

A handler for the outer exception type is still preferred if one exists. The cause is only checked when nothing matches the outer exception directly.

No. @ControllerAdvice and @RestControllerAdvice already include @Component, so component scanning picks the class up automatically. Adding @Component again does no harm, but it adds nothing.

What matters is that the class is inside a scanned package, usually the package of your @SpringBootApplication class or below it.

No. @ExceptionHandler only works in controllers and advice classes, because it is part of the web layer. In a service, the annotation is simply ignored.

Services should throw meaningful exceptions; the web layer decides how they become HTTP responses. This keeps services free of HTTP details, so the same service can be reused by a scheduled job or a message listener.

Yes. It can also hold @InitBinder and @ModelAttribute methods that apply to many controllers:

@ControllerAdvice
public class WebDefaults {

    // Trim whitespace from all incoming form fields
    @InitBinder
    public void trimStrings(WebDataBinder binder) {
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
    }

    // Make the current term available to every HTML view
    @ModelAttribute("currentTerm")
    public String currentTerm() {
        return "Autumn 2026";
    }
}

Many teams keep these in a separate class from the exception handlers, so each advice class has one clear job.

Yes, by default. It applies to every controller, so an HTML page controller would suddenly return JSON errors, which browsers display as raw text.

In applications with both kinds of controllers, limit the REST advice to REST controllers:

@RestControllerAdvice(annotations = RestController.class)
public class ApiExceptionHandler { ... }

Page controllers then fall back to HTML error pages, while API controllers get JSON.

Return a ResponseEntity, which lets you set the status, headers and body together:

@ExceptionHandler
public ResponseEntity<ProblemDetail> handleCourseFull(CourseFullException ex) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
    return ResponseEntity.status(HttpStatus.CONFLICT)
            .header("X-Waitlist-Url", "/api/waitlist")
            .body(problem);
}

Alternatively, add an HttpServletResponse parameter and call response.setHeader(...), which works with any return type.

Yes. Combine it with @ResponseStatus to send a status with an empty body:

@ExceptionHandler
@ResponseStatus(HttpStatus.NO_CONTENT)
public void handleAlreadyEnrolled(AlreadyEnrolledException ex) {
    // nothing to return: the student is already enrolled, so there is no change
}

This fits cases where the status alone says everything. If you need a body, return an object instead.

throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Course " + code + " does not exist");

Use ResponseStatusException for quick, one-off errors in a controller. For errors that appear in many places, a named exception class is clearer and easier to search for.

Yes. If the handler returns an object or ResponseEntity, Spring picks the format from the client’s Accept header automatically, as long as a converter for that format is available, for example jackson-dataformat-xml for XML.

Since Spring Framework 6.2, you can also write separate handlers per format with the produces attribute:

@ExceptionHandler(produces = "application/json")
public ResponseEntity<ErrorMessage> handleJson(CourseFullException ex) { ... }

@ExceptionHandler(produces = "text/html")
public String handleHtml(CourseFullException ex, Model model) {
    model.addAttribute("message", ex.getMessage());
    return "error/course-full";
}

Use MockMvc in standalone mode. You pass in the controller and the advice yourself, and no Spring context is started, so the test runs in milliseconds:

class EnrollmentExceptionHandlerTest {

    private final EnrollmentService service = mock(EnrollmentService.class);

    private final MockMvc mockMvc = MockMvcBuilders
            .standaloneSetup(new EnrollmentController(service))
            .setControllerAdvice(new EnrollmentExceptionHandler())
            .build();

    @Test
    void returns409WhenCourseIsFull() throws Exception {
        when(service.enroll(7L, "JAVA101")).thenThrow(new CourseFullException("JAVA101", 30));

        mockMvc.perform(post("/api/enrollments")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"studentId\": 7, \"courseCode\": \"JAVA101\"}"))
                .andExpect(status().isConflict());
    }
}

Yes. @ExceptionHandler, @ControllerAdvice, @RestControllerAdvice, @ResponseStatus and @ResponseBody are the same annotations, from the same packages, in both Spring MVC and WebFlux.

The differences are in the handler parameters and return types. Use ServerWebExchange instead of servlet types, and you may return Mono<ResponseEntity<T>>:

@ExceptionHandler
public Mono<ResponseEntity<ErrorMessage>> handleCourseFull(CourseFullException ex) {
    return Mono.just(ResponseEntity.status(HttpStatus.CONFLICT)
            .body(new ErrorMessage("COURSE_FULL", ex.getMessage())));
}

It is legal, but usually a poor idea. It catches every error from that controller, including Spring’s own exceptions for bad JSON or missing parameters, and replaces their correct 400 responses with whatever your handler returns.

Prefer handling specific exception types in controllers, and keep one carefully written catch-all in a global advice class with the lowest priority. That way, all controllers share one well-tested fallback instead of each having its own.