Exception Design in Spring Layered Architecture

Direct Answer

In a layered Spring application, use a small set of meaningful domain or application exceptions, let Spring's data-access translation handle supported persistence technologies, translate only at real abstraction boundaries while preserving causes, and map failures centrally with @RestControllerAdvice. Separate safe client messages from internal diagnostics, and do not wrap every exception at every layer.

Code Example

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) { super(message); }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(ResourceNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ApiError(404, e.getMessage()));
    }

    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ApiError> handleValidation(ValidationException e) {
        return ResponseEntity.badRequest().body(new ApiError(400, e.getMessage()));
    }
}

One place owns HTTP status mapping; controllers and services throw plain domain exceptions.

Common Mistakes & Pitfalls

• Letting SQLException leak past the repository — the service and web layers end up coupled to JDBC.
• Scattering try-catch and status codes across controllers — error mapping belongs in one @RestControllerAdvice.
• Using one generic exception for everything — distinct types like ResourceNotFoundException and ValidationException are what enable precise HTTP mapping.
• Making domain exceptions HTTP-aware — the service shouldn't know about 404; that's the advice layer's job.