Error Handling from a client perspective
In this microlearning, we will explore how the API Gateway in eMagiz handles errors and communicates responses to clients. The API Gateway operates synchronously, meaning it always provides a response to every request, whether it's successful or not. Therefore, the error handling is created in such a way that the client gets told if the response was OK or NOT OK. Our focus will be on understanding the different HTTP status codes used for error handling and how to interpret these responses to determine the outcome of your requests.
If you have any questions along the way, feel free to reach out to us at academy@emagiz.com.
1. Prerequisites
- Basic knowledge of the eMagiz platform
2. Key concepts
This microlearning centers around error handling from a client perspective for the API Gateway solution of eMagiz.
- With error handling we mean: Handling the NOT OK responses that occur in transit between API Gateway and backend operation or NOT OK response received from the backend operation.
- With client perspective we mean: How should I interpret the response from the API Gateway to determine success or failure.
- With API Gateway we mean: A collection of RESTful API operations that can be published to the outside world to give them access to applications that are linked to your business process.
3. Error Handling from a Client Perspective
Each request executed by the client will return a success or a failure response. The eMagiz API Gateway will always give back HTTP Response codes along the following lines:
- 100-level (Informational) — Server acknowledges a request
- 200-level (Success) — Server completed the request as expected
- 300-level (Redirection) — The client needs to perform further actions to complete the request
- 400-level (Client error) — The client sent an invalid request
- 500-level (Server error) — Server failed to fulfill a valid request due to an error with the server
Of these levels, the 200-level for Success calls and the 400-level and 500-level are most frequently used within the context of eMagiz. In the following sections, we will discuss the possibilities in more detail.
3.1 Success
The default response code eMagiz uses for a Success is a 200 HTTP Status Code that could be accompanied by a response body.
If the backend operation uses a 201 for example to indicate the creation of a resource in the backend eMagiz will give this back to the client making the request.
So in general terms eMagiz gives the status code back to the client that itself has received from the backend operation that is called by eMagiz.
3.2 Failure
When we zoom in on the cases where something fails we have to discern multiple scenarios:
- Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found
- Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized
- eMagiz receives a specific error from the backend operation or something goes wrong in transit -> eMagiz will return a 500 Internal Error
- eMagiz does not receive a response from the backend -> eMagiz will return a 504 Timeout Error
- A validation error occurs -> eMagiz will return a 422 Validation Error
3.3 Control the information
Apart from giving back the response codes to the client eMagiz, on default also returns the payload the moment things went wrong. From a technical perspective very handy to have, however it is not always as informative for the client calling the API operation.
As a result eMagiz auto-generates specific status codes for the three most likely scenarios that occur (422,500,504) but also provides you with the option to redefine the error handling to your own liking. To do so navigate to Design and open the catalog. In the catalog select the operation for which you want to configure this and select the tab Responses
Here you see what eMagiz has created for you on default. By pressing the Edit button on either one of them you can change things like the HTTP code you want to return and the payload you want to return when this happens.
Furthermore you can add additional response codes including the response body. To do so press the button "New".
In the pop-up that follows you can specify the HTTP Status Code response, define the body of the message and the message type of the response
To get even more control you can assign standard occurrences of errors while in transit to a certain HTTP Status Code. You can do so by pressing New under Custom Error Handler
Select the type, fill in the remainder of the details, and press Save. After you have updated your all entry and deployed it this new functionality will be in effect.
3.4 eMagiz Monitoring
Apart from sending the response back to the client eMagiz will also write a warning to the log the moment something goes wrong after eMagiz has accepted the request.
This means that cases such a the 404 and 401 do not show up here and should be dealt with by the client exclusively.
In the other scenarios where eMagiz has (attempted to) send data to a backend operation and something fails eMagiz will write a warning to the log.
On this warning, you can set up alerts for (pro-active) monitoring
4. Key takeaways
- Client calls a non-existing endpoint -> eMagiz will return a 404 Not Found.
- Client calls an endpoint without authentication or the wrong authentication -> eMagiz will return a 401 Unauthorized.
- eMagiz receives a specific error from the backend operation or something goes wrong in transit -> eMagiz will return a 500 Internal Error.
- eMagiz does not receive a response from the backend -> eMagiz will return a 504 Timeout Error.
- A validation error occurs -> eMagiz will return a 422 Validation Error.
- eMagiz also writes errors to the log for monitoring and alerting.
- You can control the information the client receives in case of an error.
5. Suggested Additional Readings
If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following link: