Applying Developer Experience Best Practices to Open Banking API Error Messages

I have worked closely with financial institutions, particularly on building banking sandboxes in Nordic and North European countries, so that third party API consumer developers can build new innovative, new customer-facing fintech products.

We all know that, with APIs offered for integration, focusing on developer experience can determine the future success of the API, which has given rise to software development focusing on the exhaustive scenarios that might unfold when a developer selects your API to integrate into their product or workflow. In the API world, focusing on that developer experience also encompasses all the error scenarios and corresponding messages that the API consumer developer may encounter.

HTTP Status Ranges

When the RFC7807 Spec is first read, it may not be considered relevant for end users and UX designers. But it is the responsibility of a development team building API integrations and the backend team to ensure that the whole API consumption experience is not compromised.

One of the interesting standards I came across in my API integration work was RFC 7807 and it answered all the possible questions around how a truly intuitive developer experience is possible when connecting external APIs and infrastructures that might be unstable or in a beta phase. (I have to be honest here, before reviewing this standard, I thought only standard HTTP response codes of 2xx success, 3xx redirect, 4xx client error, and 5xx server error were enough.)

RFC 7807 reminds us: If your API product is not doing the intended function for the end-users, it is unfit to be in market. In problem and error scenarios, it is essential to honestly communicate with users to comprehend what exactly happened, what could be the exact cause, if users should try again sooner or later, or should the product re-engage to the user when it is available.

Common Approaches to Sending Error Messages

Often, if a user interface issues an aggregated API call, whose sub-components have timed out to fetch, as integration developer you have two options

1. You can communicate the partial object state to the UI, or

2. You can fail the call completely

A similar decision is made, if it is a POST API: you can return 200 (success) or 201 (created new object successfully). In this way, it becomes a lot easier for the UI to determine if that request call influences your APIs. Also, it helps developers stay in close touch with what is happening behind the scenes.

But how should a DELETE API then behave? Maybe be offering a 204 as success code, though there is some criticism of using 204 error messages.

For API integration creator, there can be some distress felt with the choice of picking an error code to return, but what is really missing is the way to describe the problem in the calling method.

How RFC 7807 turns error messages into DX?

API integration errors like the above can better be be communicated back to the developer with a type of JSON schema, called the Problem JSON type, in RFC7807 Standard Spec.

Zalando, for example, use RFC 7807 to create  proper responsive error messages in their backend implementation.Following the example given in the RFC 7087 Spec itself, how credible is it that they  have such an error message of the problem, with ‘problem is a type’ JSON shown as:

HTTP/1.1 400 Bad Request

  Content-Type: application/problem+json

  Content-Language: en

  {

  "type": "https://example.net/validation-error",

  "title": "Your request parameters didn't validate.",

  "invalid-params": [ {

                        "name": "age",

  "reason": "must be a positive integer" },

                      {

                        "name": "color",

                        "reason": "must be 'green', 'red' or 'blue'"}

                    ]

  }

Which part of the error above do you not understand? Will it now be difficult for the UI to tell to end user? Compared with the above, how much error-code-to-error-message mapping and other DevOps overheads would this cost if you offered a “400-Bad Request” kind of error response?

My hope is that Banks API development teams can try piloting API error messages as per RFC7807 from now on, to see if this improves the developer experience for their API consumers. It will definitely be worth the effort in building your API backbone and for true interoperability and best practice API integrations.