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

Flutter: How does column layout work?

Layouts are the fundamental starting points for developing Flutter applications. There are many layout options are available by default. I am going...

Flutter: Stateless vs Stateful widgets

Flutter is a mobile application development framework developed by Google. You need to understand the fundamental building blocks before you dig deeper...

Why Flutter is a great technology for makers &...

As per the wikipedia, Flutter is an open source UI development kit created by Google. It is used to...

Why 12-Factory methodology matters to your Microservice development?

The 12-Factor application development methodology and why is it important for your microservices strategy

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...

Similar articles