RestControllerExceptionHandler constructor

const RestControllerExceptionHandler()

Creates a new instance of RestControllerExceptionHandler.

This constructor initializes a stateless exception handling component with no runtime dependencies. It is designed to be lightweight and immutable, meaning that a single shared instance can safely serve all REST controller requests within the JetLeaf runtime.

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:

Exception Type HTTP Status
BadRequestException 400 BAD REQUEST
UnauthorizedException 401 UNAUTHORIZED
ForbiddenException 403 FORBIDDEN
NotFoundException 404 NOT FOUND
MethodNotAllowedException 405 METHOD NOT ALLOWED
ConflictException 409 CONFLICT
PayloadTooLargeException 413 PAYLOAD TOO LARGE
UnsupportedMediaTypeException 415 UNSUPPORTED MEDIA TYPE
TooManyRequestsException 429 TOO MANY REQUESTS
ServiceUnavailableException 503 SERVICE UNAVAILABLE
BadGatewayException 502 BAD GATEWAY
GatewayTimeoutException 504 GATEWAY TIMEOUT
HttpException Generic HTTP error fallback

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.

Implementation

const RestControllerExceptionHandler();