congiuluc/error-handling-backend-java

Backend Error Handling (Java)

When to Use

• Setting up global exception handling with @RestControllerAdvice
• Creating custom exception types for domain errors
• Implementing the standard ApiResponse error envelope
• Mapping exceptions to HTTP status codes
• Logging errors with SLF4J structured context

Official Documentation

• Spring Boot Error Handling
• @RestControllerAdvice
• RFC 7807 Problem Details
• Resilience4j
• SLF4J

Procedure

1. Create a global @RestControllerAdvice exception handler
2. Review Java error handling patterns for advanced scenarios
3. Review exception handler sample
4. Define custom domain exceptions: NotFoundException, ValidationException, ConflictException
5. Map exceptions to HTTP status codes in the handler
6. Return ApiResponse envelope with error details — never expose stack traces
7. Log errors with SLF4J MDC context (correlation ID, user ID)
8. Use Resilience4j for retry/circuit-breaker on external calls
9. Never swallow exceptions silently

Exception Hierarchy

RuntimeException
├── NotFoundException          → 404
├── ValidationException        → 400
├── ConflictException          → 409
├── UnauthorizedException      → 401
├── ForbiddenException         → 403
└── BusinessRuleException      → 422

Global Exception Handler Pattern

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<ApiResponse<Void>> handleNotFound(NotFoundException ex) {
        log.warn("Resource not found: {}", ex.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(ApiResponse.error(ex.getMessage()));
    }

    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ApiResponse<Void>> handleValidation(ValidationException ex) {
        log.warn("Validation failed: {}", ex.getMessage());
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
            .body(ApiResponse.error(ex.getMessage()));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<Void>> handleUnexpected(Exception ex) {
        log.error("Unexpected error", ex);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(ApiResponse.error("An unexpected error occurred."));
    }
}

Error Response Envelope

public record ApiResponse<T>(boolean success, T data, String error) {

    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, data, null);
    }

    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>(false, null, message);
    }
}

Resilience Patterns

@Retry(name = "externalService", fallbackMethod = "fallback")
@CircuitBreaker(name = "externalService")
public String callExternalService() {
    return restClient.get().uri("/api/data").retrieve().body(String.class);
}

public String fallback(Exception ex) {
    log.warn("Fallback triggered for external service: {}", ex.getMessage());
    return "default";
}

Constraints

• NEVER expose stack traces in API responses
• ALWAYS log the full exception at error level for unexpected errors
• ALWAYS use typed exceptions — avoid throwing raw RuntimeException
• ALWAYS include correlation ID in error logs via MDC
• ALWAYS return ApiResponse envelope — never raw error bodies