Define a custom exception hierarchy to make errors self-documenting and enable precise handling; 2. Use @ControllerAdvice for centralized, consistent error response formatting; 3. Apply the Circuit Breaker pattern with Resilience4j to prevent cascading failures; 4. Implement retry with backoff and jitter to handle transient failures gracefully; 5. Enhance observability with structured logging, MDC, metrics, and APM tools; 6. Ensure idempotency using idempotency keys to safely handle duplicate requests; 7. Design for graceful degradation with fallbacks and feature toggles when dependencies fail; 8. Validate inputs early using Bean Validation to fail fast and reduce downstream errors; together, these practices build resilient, observable, and maintainable Java microservices that handle errors as manageable events rather than outages.

When building Java microservices, error handling is more than just catching exceptions—it’s about resilience, observability, and user experience. As systems grow in complexity, basic try-catch blocks are no longer sufficient. Advanced error handling patterns help maintain service stability, improve debugging, and ensure graceful degradation. Below are key patterns and practices used in production-grade Java microservices.

1. Structured Exception Handling with Custom Exception Hierarchy

Instead of throwing generic exceptions like RuntimeException, define a clear exception hierarchy tailored to your domain.

Why it matters:

• Makes error types self-documenting.
• Enables precise exception handling at different layers.
• Simplifies logging and monitoring.

Example:

public abstract class ServiceException extends RuntimeException {
    protected final String errorCode;
    protected final int httpStatus;

    public ServiceException(String message, String errorCode, int httpStatus) {
        super(message);
        this.errorCode = errorCode;
        this.httpStatus = httpStatus;
    }

    // getters...
}

public class ValidationException extends ServiceException {
    public ValidationException(String message) {
        super(message, "VALIDATION_ERROR", 400);
    }
}

public class ResourceNotFoundException extends ServiceException {
    public ResourceNotFoundException(String message) {
        super(message, "NOT_FOUND", 404);
    }
}

Then, use a global exception handler (e.g., with Spring’s @ControllerAdvice) to translate these into consistent HTTP responses.

2. Global Exception Handling with @ControllerAdvice

Centralize error response formatting using a global exception handler.

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ServiceException.class)
    public ResponseEntity<ErrorResponse> handleServiceException(ServiceException ex) {
        ErrorResponse error = new ErrorResponse(ex.getMessage(), ex.getErrorCode());
        return ResponseEntity.status(ex.getHttpStatus()).body(error);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        ErrorResponse error = new ErrorResponse(message, "VALIDATION_ERROR");
        return ResponseEntity.status(400).body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericException(Exception ex) {
        ErrorResponse error = new ErrorResponse("Internal server error", "INTERNAL_ERROR");
        // Log the actual exception
        return ResponseEntity.status(500).body(error);
    }
}

This avoids duplicated error response logic across controllers.

3. Circuit Breaker Pattern for Fault Tolerance

When a downstream service is failing, repeatedly trying to call it wastes resources and increases latency. The Circuit Breaker pattern prevents this.

Tools: Use Resilience4j or Sentinel (not Hystrix, which is deprecated).

Example with Resilience4j:

@CircuitBreaker(name = "paymentService", fallbackMethod = "fallbackCharge")
public PaymentResponse chargePayment(PaymentRequest request) {
    return paymentClient.charge(request);
}

public PaymentResponse fallbackCharge(PaymentRequest request, CallNotPermittedException ex) {
    log.warn("Circuit breaker is open, returning fallback");
    return PaymentResponse.scheduled(); // graceful fallback
}

Configure in application.yml:

resilience4j.circuitbreaker:
  instances:
    paymentService:
      failure-rate-threshold: 50
      wait-duration-in-open-state: 5000ms
      sliding-window-size: 10

This prevents cascading failures during outages.

4. Retry with Backoff and Jitter

Transient failures (e.g., network glitches) are common in distributed systems. Retry with exponential backoff increases success chances.

With Resilience4j Retry:

@Retry(name = "inventoryService", fallbackMethod = "fallbackCheckStock")
public boolean checkStock(String itemId) {
    return inventoryClient.check(itemId);
}

// Fallback if all retries fail
public boolean fallbackCheckStock(String itemId, Exception ex) {
    return false;
}

Configure retry:

resilience4j.retry:
  instances:
    inventoryService:
      max-attempts: 3
      wait-duration: 1000ms
      enable-exponential-backoff: true

Adding jitter (random delay) prevents thundering herd problems.

5. Error Tracking and Observability

Even with good handling, errors must be visible. Integrate logging, metrics, and tracing.

Key practices:

• Use MDC (Mapped Diagnostic Context) for request-level tracing.
• Log exceptions with structured JSON (e.g., via Logback Logstash).
• Report errors to APM tools like Datadog, New Relic, or OpenTelemetry.

Example with SLF4J and MDC:

MDC.put("requestId", requestId);
try {
    // business logic
} catch (ServiceException ex) {
    log.error("Service error: {}, code: {}", ex.getMessage(), ex.getErrorCode(), ex);
    throw ex;
} finally {
    MDC.clear();
}

Also emit metrics:

meterRegistry.counter("service.errors", "type", "validation").increment();

6. Idempotency to Handle Duplicate Requests

Network issues can cause clients to retry requests, leading to unintended side effects (e.g., double payment).

Solution: Use idempotency keys.

@PostMapping("/orders")
public ResponseEntity<?> createOrder(@RequestHeader("Idempotency-Key") String key, @RequestBody OrderRequest req) {
    return idempotencyService.execute(key, () -> orderService.create(req));
}

The idempotencyService checks if the key was already processed (e.g., using Redis with TTL). If yes, returns the cached result; otherwise, runs and caches the outcome.

7. Graceful Degradation and Fallbacks

When non-critical services fail, degrade functionality instead of failing entirely.

Examples:

• Return cached product recommendations if recommendation engine is down.
• Allow cart modification even if inventory service is slow (with warning).

Use fallbacks in CircuitBreaker or implement feature toggles (via Togglz or FF4J).

8. Validating Inputs Early (Fail Fast)

Catch errors at the edge—don’t let invalid data propagate.

Use Bean Validation (JSR-380) with annotations:

public class PaymentRequest {
    @NotBlank
    private String userId;

    @DecimalMin("0.01")
    private BigDecimal amount;
}

And validate in controllers:

@PostMapping("/pay")
public ResponseEntity<?> pay(@Valid @RequestBody PaymentRequest req) { ... }

This reduces error handling burden downstream.

Basically, advanced error handling in Java microservices isn’t just about catching exceptions—it’s about designing for failure. Use structured exceptions, circuit breakers, retries, observability, and fallbacks to build systems that are resilient and maintainable. These patterns, when combined, turn errors from outages into manageable events.

The above is the detailed content of Advanced Error Handling Patterns in Java Microservices. For more information, please follow other related articles on the PHP Chinese website!