A centralised Exception handling within a web framework is an important aspect of your application. The functionality that is provided by your code for the client is probably the most important aspect. But not every request can be successfully processed. Not to mention that your application can receive malicious requests that should be handled gracefully.
A centralised handling is highly recommended so that you can handle these exceptional cases uniformly. In this blog, I’ll explain how you can achieve such a centralised handling within Kotlin Ktor that is outside of your business code.
Types of Errors
There are several types of Errors that your applications should handle. Let us go over each of them and how you can handle them. In the next step, we will then handle all Exceptions in a central place.
Missing URL parameters
Within Ktor, we define the template URLs that we like to handle. many of these URLs have a placeholder in them so that we can handle similar requests by the same piece of code. But the values for these placeholders might be missing or wrong.
Let us consider the URL that we define to retrieve detailed information about a product of our webshop based on its id.
GET /product/{productId?}
And we can have multiple URLs in our application that all have a productId parameter in the template. We can use a helper method to retrieve this parameter from the URL and call it in each case we have thus productId parameter.
fun extractProductId(context: PipelineContext<Unit, ApplicationCall>): String {
return context.call.parameters["productId"] ?: throw HasMissingParameterException("Missing 'productId' in URL")
}
The HasMissingParameterException is a RuntimeException that we will handle later on. And we can create such a helper function for each template variable our application has and group them in a Kotlin file.
The reason we have defined the parameter as optional (the ? at the end of the name) allows us to handle the absence of the parameter. The client may, on purpose or by accident due to a problem in their own code, send requests like /product/. Due to the optional marker, the same code will be executed within our Ktor application and a HasMissingParameterException will be thrown.
In the next section, we will see how these HasMissingParameterException exceptions will be handled.
Incorrect ids
Related to the previous paragraph where we handled the productId, we should verify if the productId is a valid value.
If we always expect that the productId is a numeric value, a positive long value for example, we can incorporate this check into the extractProductId function we used earlier. Instead of returning the value immediately as in the above example, we can try to convert the String value to a Long.
If that fails, we can throw another exception to indicate this problem.
Further on in the processing of our request, we need to check if the productId that is specified is an existing value. It might be a positive value but the number might not be a product that exists in our database.
When our code finds this out, it can throw an exception to indicate the entity is not found. Our generic Exception handling can pick this up and responds with the HTTP status 404.
See the example application and the BookEntityNotFoundException class for an example of this scenario. (project on GitHub )
Business logic error
The last category of errors we need to handle is business logic errors. If the request that we are handling violates one of the business rules we have defined, an order cannot be made for a customer that has more than x euro open invoices, and the request should be aborted.
Our code can throw an exception at this point and our generic exception handling will do the rest. Our code doesn’t need to know how to handle it, it just needs to show a custom exception.
All these exceptions should extend from a common exception, like BusinessException so that we can handle these cases easily in our ExceptionHandler.
Sending errors to the client
Now that we have proper Exceptions thrown at the various points in our code, we need a central place where we can handle them. This way, our business logic is not tight to the handling of the requests and can be reused in other scenarios.
We can install an ExceptionHandler through the StatusPage functionality of Ktor. So make sure you have added this module to your application. But it is not much trouble to add it later on as it just required the Maven artefact.
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-status-pages-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
Installing the handler within the Ktor framework is also very straightforward. You need the following snippet to forward the exception handling to the handle() method
install(StatusPages) {
exception<Throwable> { call, cause ->
ExceptionHandler.handle(call, cause, developmentMode)
}
}
The development mode variable is a boolean that indicates if you started the application in development mode. It can be used to give more information in the response or in the log about the exception that occurred. When in production mode, the code makes sure that no internal information is returned to the caller that might give some hints to malicious users about your application internals and how it can be abused. In the end, it is up to you and the additional components you use in your environments how to deal with Exception.
But don’t print a stack trace for each business logic or conversion error from String to Long when retrieving parameters. As these exceptions are thrown to easily handle error responses and are not some kind of error in your code, but are expected.
What does the handle method look like?
when (cause) {
is EntityNotFoundException -> {
// for the cases the user specified an URL parameter where the id doesn't exist.
call.respond(
HttpStatusCode.NotFound,
ExceptionResponse(cause.message ?: cause.toString(), HttpStatusCode.NotFound.value)
)
}
is BusinessException -> {
// Some business logic error, status 412 Precondition Failed is appropriate here
call.respond(
HttpStatusCode.PreconditionFailed,
ExceptionResponse(cause.message ?: cause.toString(), cause.messageCode.value)
)
}
is ParameterException -> {
// The client forgot to define a Path or Query parameter or used a wrong type (string and not a number)
call.respond(
HttpStatusCode.BadRequest,
ExceptionResponse(cause.message ?: cause.toString(), HttpStatusCode.BadRequest.value)
)
}
// We can have other categories
else -> {
// All the other Exceptions become status 500, with more info in development mode.
if (developmentMode) {
// Printout stacktrace on console
cause.stackTrace.forEach { println(it) }
call.respondText(text = "500: $cause", status = HttpStatusCode.InternalServerError)
} else {
// We are in production, so only minimal info.
call.respondText(text = "Internal Error", status = HttpStatusCode.InternalServerError)
}
}
This is the code from the example project I prepared for this blog. It can be adapted to the needs of each specific application. The overall idea is that you have a specific HTTP status for each type of problem. The ParameterException, indicating a missing or wrong type for a path or query parameter results in status 400. EntityNotFoundException when an id is not found in the database and BusinessExceptions indicating a business rule violation results in status 404 and 412 respectively.
All other exceptions result in status 500 and when in development mode, more info is available in the response and in the log.
The body of those errors is a JSON object that is created from the data class ExceptionResponse. It contains a code and a short message so that the client has some information about what went wrong. Since most of the HTTP status codes returned by this handler are in the 400 range, meaning they are client errors. the client did send a request which was incorrect so it should receive some feedback on what was wrong.
Conclusion
Proper Exception handling is an important part of your application. As a best practice, not every method should deal with returning the proper response as that would mean that your business code knows about the type of client. Instead, you should throw Exceptions, all having a specific parent that indicates the type of problem that occurred. Types are related to the parameters of the request, non-existing ids that are provided, or violations of business rules. Other types of problems can exist depending on the application. Regardless of the number of types, a centralised exception handler, installed as StatusPage handler within Ktor, the correct HTTP status and response body can be sent back from a single method. And don’t forget to include some code and a short description of the problem so that the client knows what went wrong. Without giving away too many details of the internals of your application in case a malicious user tries to figure out your application by sending random or incorrect requests on purpose.
You can find an example of how you can implement this strategy in the project located at https://github.com/rdebusscher/kotlin-projects/tree/main/ktor-exceptions.
Training and Support
Do you need a specific training session on Kotlin, Jakarta EE or MicroProfile? Or do you need some help in getting up and running with your next Ktor project? Have a look at the training support that I provide on the page https://www.atbash.be/training/ and contact me for more information.