Tech Blog

Error Handling with APIs

Errors happen, all the more so when working with external systems, so it’s important that we handle them properly. As a part of the published Ex Libris philosophy for building REST APIs, errors are returned from Alma with a 400 response code and a response body with details on what caused the error. Sometimes error conditions may be expected and we want to handle it in our logic flow (e.g. a record doesn’t exist), and other times all we can do is log the error and gracefully display an error message to the user.

In this post, we’ll explore how to handle an error response in several different programming environments. For each example, we’ll call the Get Users API with an invalid primary ID. Our goal is to the use the native error handling paradigm of the particular programming environment. We then parse the response to extract the errorMessage property in the response from Alma, and use it to report back to the user. Alternatively, our code can identify expected scenarios via the errorCode value and handle the scenario (for example, creating a new record if one doesn’t already exist). Expected errors and their respective codes are documented for each API (e.g. the Retrieve User API).

CURL

In this example, we won’t handle the error, but rather we’ll look at the response in more detail.

When we run the script, we get:

$ bash curl.sh
> GET /almaws/v1/users/fdsa HTTP/1.1
> Host: api-na.hosted.exlibrisgroup.com
> accept: application/json
> authorization: apikey ***
> 
< HTTP/1.1 400 Bad Request
< X-Exl-Api-Remaining: 8996176
< Content-Type: application/json;charset=UTF-8
< Content-Length: 188
< 
{
  "errorsExist": true,
  "errorList": {
    "error": [
      {
        "errorCode": "401861",
        "errorMessage": "User with identifier fdsa was not found.",
        "trackingId": "E01-1312124118-MORQS-AWAE1344225209"
      }
    ]
  },
  "result": null
}

We notice in the response that the status code is 400, and the response body contains the error object.

Node.js

In this example, we’re using the “got” library for making HTTP requests. We wrap our request in a JavaScript try/catch, and we display the errorMessage in the catch block.

Ruby

In this example, we’re using the “Faraday” library for making HTTP requests. We wrap our request in a Ruby begin/rescue, and we display the errorMessage in the rescue block.

Python

In this example, we’re using the “Requests” library for making HTTP requests. We wrap our request in a Python try/except, and we display the errorMessage in the except block.

PHP

In this example, we’re using the PHP wrapper of CURL. CURL doesn’t return the response body if the response code is not 200, so we need to set the CURLOPT_FAILONERROR option to false, and then check the response code before proceeding with our processing.

Summary

Using the methodology described in this post, we’re able to leverage the Alma APIs and the infrastructure and best practices of our development environment to handle errors gracefully.