Skip to content

Exceptions.md

Latest commit

 

History

History
70 lines (56 loc) · 3.65 KB

Exceptions.md

File metadata and controls

70 lines (56 loc) · 3.65 KB
Raw

Exceptions System

The Exceptions system provides a centralized, uniform way to handle errors across all layers and return consistent JSON responses to the client.

Components

GlobalErrorHandler

  • Purpose: Static utility for mapping exceptions to HTTP responses.
  • Handling Strategy:
    • ServiceException: Maps custom business errors (e.g., EMPLOYEE_NOT_FOUND) to their defined ErrorCode.
    • DecodeException: Handles JSON parsing failures (REQ_001).
    • BadRequestException (v4.5): Handles OpenAPI validation errors from RouterBuilder. Returns VALIDATION_ERROR.
    • ReplyException: Maps Event Bus failures (e.g., failed authentication from UserVerticle → 401 Unauthorized) to appropriate HTTP status codes.
    • Generic Exceptions: Catches unexpected crashes (GEN_001) and returns 500 Internal Server Error.
  • Response Mechanism: Uses the ApiError DTO to ensure a consistent JSON structure.
  • Logging: Uses SLF4J to log critical failures, replacing legacy System.err calls.

ErrorCode

  • Purpose: A centralized registry of all possible system errors.
  • Fields per Entry:
    • httpStatus: Standard HTTP code (e.g., 404, 429).
    • code: Unique internal identifier (e.g., EMP_001, SEC_001) for debugging.
    • message: Default human-readable description.

ServiceException

  • Purpose: Custom RuntimeException used throughout the service and repository layers.
  • Role: Allows logic to "fail fast" with a specific ErrorCode, which the web layer can then easily translate for the client.

Standardized Error Response (ApiError)

All errors follow this unified JSON format:

{
  "code": "EMP_001",
  "message": "Employee with the provided ID was not found.",
  "timestamp": "2026-01-15T14:45:00Z"
}

Exception Handling Cases

Case Exception Type Error Code HTTP Status
1 ServiceException From exception From ErrorCode
2 DecodeException REQ_001 400
3 BadRequestException (v4.5) VALIDATION_ERROR 400
4 ReplyException Mapped from code Variable
5 Generic Throwable GEN_001 500

Error Propagation Flow

  1. Source: An error occurs in the Repository, Service, Handler, or OpenAPI validation.
  2. Signal: A ServiceException (or BadRequestException from RouterBuilder) is thrown or a Future is failed.
  3. Capture:
    • For OpenAPI validation: RouterBuilder throws BadRequestException → GlobalErrorHandler catches.
    • The Controller catches the failure from the Event Bus and maps it back to a ServiceException.
    • Vert.x Web failureHandler or explicit try-catch in handlers calls GlobalErrorHandler.handle().
  4. Resolution: GlobalErrorHandler serializes the ApiError and sends it to the client with the correct HTTP status.

OpenAPI Validation Errors (v4.5)

When a request fails OpenAPI schema validation, RouterBuilder throws a BadRequestException. The error message contains details about which field failed validation:

{
  "code": "VALIDATION_ERROR",
  "message": "$.password: is missing but it is required",
  "timestamp": "2026-01-29T12:00:00Z"
}