RestControllerExceptionHandler class

A centralized exception handling component for RESTful controllers in the JetLeaf Web framework.

The RestControllerExceptionHandler serves as the default global exception translator for REST APIs. It intercepts exceptions thrown by controller pods and converts them into standardized JSON or structured response bodies using ResponseBody.

Purpose

JetLeaf’s REST controller layer is designed for explicit exception-based flow control. Rather than returning raw error codes, controllers may throw typed exceptions (such as BadRequestException, NotFoundException, or ServiceUnavailableException).
The RestControllerExceptionHandler automatically maps these to valid HTTP responses, ensuring consistent structure and behavior across the application.

Each handler method is annotated with `@ExceptionHandler`, linking a specific exception type to a corresponding HTTP response. The returned ResponseBody object encapsulates:

• the HTTP HttpStatus code,
• an error description or diagnostic message,
• optional details (metadata, validation errors, etc.),
• and a timestamp for traceability.

Features

• Consistent REST error format — all responses are standardized.
• Automatic mapping of exceptions to HTTP status codes.
• Extensible design — developers can subclass or replace this handler to customize error payloads or serialization rules.
• Stateless & reusable — safe to use across multiple web requests.

Supported Exception Types

The following exception classes are supported by default:

Example

@RestController()
class AccountController {
  @Get('/accounts/:id')
  Future<Account> getAccount(@PathVariable('id') String id) async {
    final account = await repository.findById(id);
    if (account == null) throw NotFoundException('Account not found');
    return account;
  }
}

If NotFoundException is thrown, this handler automatically returns:

{
  "error": "Not Found",
  "message": "Account not found",
  "timestamp": "2025-11-07T12:34:56.789Z"
}

Integration

The handler is automatically registered in JetLeaf’s web dispatcher pipeline. It applies only to REST controllers, ensuring that web controllers rendering views use ControllerExceptionHandler instead.