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
Top comments (3)
My thoughts exactly! On a recent hackathon project, the frontend dev wanted an optimal error handling functionality that covers most client (4xx) errors. Extended the default JS Error object to include some new properties when we do "throw new Error" but it seemed hacky, until I went back to properly define the specs of the API response and then everything worked seamlessly.
Also, I see you're hiring full-stack devs. Do you have any open positions for juniors or internships, maybe? I would be really interested.
we have open positions gist.github.com/sibelius/ce9499969...
but we are only hiring in Brazil yet
Just read through the Q&A now. Exciting stuff! I think it's great you're prioritizing doers and builders who can get stuff done on their own. You said internships would be reopened this year so I'm really looking forward to that. Like I said, I'm quite passionate about working in Fintech and specifically payments. I'd love to connect on LinkedIn, if that's okay with you🙂