Helix Framework Documentation

Example

Custom Error Handler

Demonstrates how to implement a custom HelixErrorHandler and let the global Helix error handler delegate to it. Shows a Spring-managed handler bean, business-specific error mapping, and the standard Helix error envelope around the custom response.
Group
REST API
Path
examples/rest-api/custom-error-handler
Source README

Overview

Helix Spring Boot webservice that demonstrates how to register a custom HelixErrorHandler and have it invoked by

the global Helix error handler.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


./gradlew -p examples runExample -Pexample=rest-api/custom-error-handler --init-script "$(pwd)/helix.init.gradle"

What It Shows

  • the Helix API starter baseline
  • the standard Helix response envelope
  • a feature-specific runtime exception that is not annotated with @HelixException
  • a Spring-managed HelixErrorHandlerAdaptor implementation
  • automatic discovery of custom handlers by the Helix global error handler
  • a custom error response that still uses the standard Helix envelope

Endpoints

  • GET /v1/invoices/{region}
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "region": "us-east",
    "processor": "stripe",
    "enabled": true
  }
}

Example error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "code": "INVOICE-REGION-409",
    "status": 409,
    "message": "Invoice processing is not enabled for region 'antarctica'.",
    "attributes": {
      "region": "antarctica",
      "supportedRegions": [
        "us-east",
        "eu-west"
      ]
    }
  }
}

Development

Building the Application

Run the following command to build the service:

Command

Building the Application


./gradlew clean build

Testing the Application

Run the following command to run the service tests:

Command

Testing the Application


./gradlew test
./gradlew integration

Trying the API

Run the service:

Then try:

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/invoices/us-east

curl http://localhost:8080/v1/invoices/antarctica