Helidon: Custom exception with Exception Mapper

Having a custom exception is a standard programming practice. Instead of having various exceptions (Native), wrapping those exceptions with our well-defined custom business exceptions offers full control over our exception handling practices. In this article, I am going to explain, how to write custom exceptions with the Helidon framework during the microservice development.

Since the Helidon framework, simply follows Microprofile specification, we can use JAX-RS capabilities to get the job done.


  1. Implement custom exception
  2. Implement custom exception mapper
  3. Bind the custom exception in the application

Next, we will go through each step in detail.

Custom exception (DailyApiException.java)

public class DailyApiException extends Exception {
    private int code = 500;

    public DailyApiException(String message) {

    public DailyApiException(int code, String message) {
        this.code = code;

    public DailyApiException(String message, Throwable cause) {
        super(message, cause);

    public int getCode() {
        return code;

Custom exception mapper (DailyApiExceptionMapper.java)

public class DailyApiExceptionMapper implements ExceptionMapper<DailyApiException> {
    public Response toResponse(DailyApiException e) {
        Map<String, Object> entities = new HashMap<>();
        entities.put("code", e.getCode());
        entities.put("message", e.getMessage());
        return Response

Bind exception mapper into application

public class DailyApiApplication extends Application {

    public Set<Class<?>> getClasses() {
        return CollectionsHelper.setOf(
                DailyApiExceptionMapper.class, //Exception mapper

Finally, in our API implementation, we can directly throw the custom exception based on our business conditions like below,

Response all() throws DailyApiException;

Response get(@PathParam("code") String code) throws DailyApiException;

I believe now you have got a clear understanding of how to implement custom exceptions in our APIs. Please share your feedback if you have any!

{ happy coding }

API Evangelist | Chief Hustler @workrituals.com | Habit Coach | Madras Java User Group Leader

Latest articles

When to use Firebase Cloud functions?

Recently I got a question from one of the Indie makers that, when to use Firebase Cloud Functions? This...

Jakarta Tech Talk: Build Microservice using Microprofile + Helidon

Recently I gave a presentation on Jakarta Tech Talk series on 'Building a Microservice using Microprofile + Helidon. Enjoy watching the presentation...

Serverless REST APIs made simple with Cloud functions

Introduction Serverless is one of the top keyword in the integration space right now. Everyone is talking about the...

How to get started with Google cloud functions?

The 'Cloud Functions' is a Google technology bundled as part of the Firebase platform. It is a serverless backend to support our...

Why Firebase is a great technology for ‘Indie Makers’...

Firebase is a technology developed by Google. In this article, I am going to explore why Firebase is a great technology for...

Similar articles