Best Practices for Validation and Exception Handling in Spring Boot (With HTTP Status Codes & Frontend Handling)

[poksyy]

When handling validation and business logic errors in Spring Boot, it's important to return clear, structured error responses to the frontend. This allows Kotlin Compose (or any frontend) to handle errors dynamically based on HTTP status codes and messages.

✅ 1. Handling Validation Errors (400 Bad Request) with Jakarta Validation

For basic validation (e.g., missing fields, incorrect formats), we use DTOs with Jakarta annotations.

📌 Example (UserRegisterRequest.java)

public record UserRegisterRequest(
    @NotBlank(message = "Username cannot be blank") String username,
    @Email(message = "Must be a valid email") String email,
    @NotBlank(message = "Password cannot be blank") String password
) {}

🔹 What happens when validation fails?
Spring Boot automatically throws a MethodArgumentNotValidException, which results in a 400 Bad Request response.
📌 Example response from the backend:

{
    "username": "Username cannot be blank",
    "email": "Must be a valid email",
    "password": "Password cannot be blank"
}

✅ 2. Handling Business Logic Errors (409 Conflict, 500 Internal Server Error, etc.)

For errors like "User already exists", we centralize handling using @ControllerAdvice. info
📌 Example (GlobalExceptionHandler.java)

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserAlreadyExistsException.class)
    public ResponseEntity<Map<String, String>> handleUserAlreadyExists(UserAlreadyExistsException ex) {
        return ResponseEntity.status(HttpStatus.CONFLICT)
                .body(Map.of("error", ex.getMessage()));
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationErrors(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error ->
                errors.put(error.getField(), error.getDefaultMessage()));
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors);
    }
}

🔹 What happens when a business logic error occurs?
For example, if a user tries to register with an already existing email, the backend will return:
📌 Example response (409 Conflict - User already exists):

{
    "error": "User with this email already exists"
}

✅ 3. How the Frontend Handles These Errors (Kotlin Compose)

📌 Step 1: Check if the response is successful

if (!response.isSuccessful) {
    val errorBody = response.errorBody()?.string()
    val errorMap = parseError(errorBody)
    
    _uiState.value = UiState.Error(errorMap) // Display errors dynamically in UI
}

📌 Step 2: Parse Errors Based on HTTP Status Code

private fun parseError(errorBody: String?): Map<String, String> {
    return try {
        val jsonObject = JSONObject(errorBody ?: "{}")
        jsonObject.keys().asSequence().associateWith { jsonObject.getString(it) }
    } catch (e: Exception) {
        mapOf("error" to "An unexpected error occurred")
    }
}

🔹 Why Use HTTP Status Codes for Error Handling?

HTTP Status Code	When It Occurs	How to Handle It in Frontend
400 Bad Request	Validation errors (missing fields, invalid email, etc.)	Display validation messages for each field.
401 Unauthorized	User authentication fails (wrong password, invalid token)	Show login error message.
403 Forbidden	User lacks permission to access a resource	Show an "Access Denied" message.
409 Conflict	Business logic error (e.g., user already exists)	Show specific error message like "User already exists".
500 Internal Server Error	Unexpected errors	Display a generic error message and log the issue.