Error Handling in REST API

REST API provides a public/private interface to interact with a system.
Even though you provide good OpenAPI documentation, a type-safe SDK, you can't avoid APIs being used wrong.
There are also situations where even when using the API in the right way, you can get some unexpected or expected errors.

HTTP Status Code

We can use the HTTP Status Code to provide some common errors that happen to all APIs, here is a list of a few of them:

2xx - successful response
200 - success
3xx - redirections responses
301 - redirect
4xx - client error responses
400 - bad request
401 - Unauthorized
403 - Forbidden
5xx - server error responses
500 - internal server error

Return a 2xx status code when the request is a success.
Return a 3xx status code when the server redirects to another endpoint.
Return a 4xx status code when the client used the API in the wrong way.
Return a 5xx status code when the server behaves in unexpected ways.

A 4xx usually means a bug in the client code that is consuming the API.
A 5xx usually means that the server has a bug.

Check more status code here: Status Code

When the status code is not enough

When a client receives a 4xx error, they want to know why they received that error.
A simple approach would be to return an error field in the response payload. Example:

{
  "error": "Pix Key not found"
}

The problem with this approach is that uses a pure string for the error. A pure string is good enough for a human to read the error, but not for machines.

Problems Details and Error Codes

To solve this problem, and provide good errors for machines.
We have the Problem Details for HTTP APIs that defines a standard for Errors on API.

Below is an example of the error output:

{
    "type": "https://api.woovi.com/errors/pix-key-not-found",
    "title": "Pix Key not found",
    "detail": "The Pix Key is not registered in a payment institution",
    "instance": "/alias/e553cee3-b2d2-498c-8a56-26249b797b92",
    "status": 400
}

If you want to write a client that handles the pix key not found error differently, you can just check the type field of the error.

Errors that should be Error Codes

Based on our experience, you need Error codes for errors that are expected to happen even though everything is fine.

For instance, we have an API that enables users to send an Instant Payment (Pix) payment to a Pix Key. This API has some known expected errors that can happen:

pix key not found
not enough balance
payment rejected

For each of these errors, our users need to handle them in different ways.

Summary

To create a great API, you need to think carefully about how you handle error handling. A good error detail or experience is the difference that will make your user integrate with your API or just give up.
A good error on the API will also reduce support requests.
A good and reliable API will make onboarding faster, increase the conversion rate, and reduce churn.
A great API is good for business.

Woovi
Woovi is a Startup that enables shoppers to pay as they like. To make this possible, Woovi provides instant payment solutions for merchants to accept orders.

If you want to work with us, we are hiring!

Photo by Image by storyset

Provide the best Error Handling for your API