Error Handling

Error Response Structure

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Must be a valid email address",
        "rejectedValue": "not-an-email"
      }
    ],
    "timestamp": "2025-01-15T10:30:00Z",
    "traceId": "abc-123-def",
    "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}

Error Categories

Category	Status	Example
Client errors	4xx	Invalid input, unauthorized
Server errors	500	Unexpected failures
Business errors	422	Rule violations
Transient errors	503	Temporary unavailability

Global Exception Handler (Spring)

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(
            ResourceNotFoundException ex) {
        return ResponseEntity.status(404).body(
            ErrorResponse.builder()
                .code("RESOURCE_NOT_FOUND")
                .message(ex.getMessage())
                .timestamp(Instant.now())
                .build()
        );
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(
            MethodArgumentNotValidException ex) {
        List<FieldError> errors = ex.getBindingResult()
            .getFieldErrors().stream()
            .map(e -> new FieldError(e.getField(), e.getDefaultMessage()))
            .collect(Collectors.toList());
        return ResponseEntity.status(422).body(
            ErrorResponse.builder()
                .code("VALIDATION_ERROR")
                .message("Validation failed")
                .details(errors)
                .build()
        );
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneral(Exception ex) {
        log.error("Unexpected error", ex);
        return ResponseEntity.status(500).body(
            ErrorResponse.builder()
                .code("INTERNAL_ERROR")
                .message("An unexpected error occurred")
                .traceId(MDC.get("traceId"))
                .build()
        );
    }
}

Design Principles

• Use nouns, not verbs
• Plural resource names
• Consistent naming conventions
• Proper HTTP status codes

Versioning

• URI versioning (/v1/resource)
• Header versioning
• Deprecation policy

Documentation

• OpenAPI/Swagger specs
• Request/Response examples
• Error code documentation
• Rate limit documentation

Key Points

• Understanding API Error Handling is essential for production systems
• Always consider scalability and maintainability
• Test thoroughly before deploying to production
• Monitor performance and set up alerting

Common Patterns

1. Validation: Always validate input at the boundary
2. Error Handling: Use structured error responses
3. Logging: Log key events for debugging
4. Testing: Unit, integration, and load tests
5. Documentation: Keep docs updated with code changes