FieldVal Tackles Lackluster API Error Handling

A new JavaScript Library called FieldVal aims to solve some of the biggest problems associated with API error handling.

According to FieldVal's creator, Marcus Longmuir, "Every form, parameterized page or API request needs some form of validation. The clearer the errors, the easier it is to correct problems with the input. Quite simply – the better the validation, the better the user/developer experience."

Unfortunately, the quality of validation frequently falls short. Basic form Error Handling, for instance, often returns one error at a time, and errors consist of simple strings that aren't explicitly associated with the form fields that handled them.

This lackluster error handling often extends to API responses. In a blog post descriptively entitled Most API Errors Suck, Longmuir provides a theoretical example of an API response:

    "message": "error",
    "errors": [
        "Missing destination email"

"Without manually matching that string, how would you go about presenting this error to an end user?" he asks.

Such poorly-structured API responses are not merely theoretical. To prove this point, Longmuir points to a response from a Facebook Graph API Endpoint that returns an authenticated user's friends:

    "error": {
       "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100

This error structure is practically "useless" because it offers the offending client no real information about what the error actually is and how the client or its user can resolve the error.

FieldVal seeks to eliminate these types of responses by providing a better structure for errors, one that is meaningful, readable and parseable. For example, a request containing a field named age that was expecting a numeric value but received a string value would instead produce the following FieldVal response:

    "invalid": {
        "age": {
            "error_message": "Incorrect field type. Expected integer.",
            "error": 2,
            "expected": "integer",
            "received": "string"
    "error_message": "One or more errors.",
    "error": 5

With FieldVal, the nature of the error is clear, errors can easily be handled programatically, and errors are explicitly associated with the offending parameter, making it possible for client applications to display meaningful error information in a User Interface. Additionally, if there are multiple errors present, they are included in the response, so client applications can address them all in a single request.

The FieldVal JavaScript library is available on GitHub, and can also be installed via NPM or Bower. There is also a FieldVal UI library which is designed to speed the implementation of forms that leverage FieldVal.

The real reason error handling falls short

FieldVal looks like it provides a good structure for API error handling, and even if it does not become a widely used standard, serves as a useful reference for developers thinking about how their APIs deliver error responses. Unfortunately, the reason error handling falls short is that many developers frequently give short shrift to error handling. After all, errors shouldn't occur and when not forced to reconsider this, API error structures are often implemented based on the misguided assumption that legitimate errors won't be frequent.

Error handling is particularly easy to overlook in environments in which the developers who are responsible for implementing APIs aren't forced to eat their own dogfood. Poor error responses become readily apparent when developers consume the APIs they build, so it's important for developers to build their own client applications, even if only for testing purposes. As Leore Avidar, the co-founder of Lob, an API-centric printing and mailing startup, told me when discussing API-first development, "Whether you are building your website using your API or building sample applications it will help you anticipate how your clients will use it as well as find all the early bugs and problems." Those problems, of course, include dealing with frustratingly inadequate error responses.

The good news is that organizations can make dogfooding a mandatory part of their API development process. When this happens, the need for better error handling structures like that offered by FieldVal will become more apparent.

Be sure to read the next API Design article: Dropbox Sparks Controversy With API Design Decision