API Error Handling
Introduction
When dealing with a web API such as the Scantrust API, it is important to deal with errors accordingly. Several industry standard errors may occur during calls to our API. This document summarizes those errors and how to deal with them.
Traditionally each error response has a status code and a response body (additional text information).
Status code overview
Success codes - No error
| Status Code | Short | Description |
|---|---|---|
| 200 | OK | Request processed successfully |
| 201 | CREATED | Request processed successfully and created an instance |
| 204 | NO CONTENT | Request processed successfully, no body returned |
| 301 | MOVED PERMANENTLY | Permanent redirect |
| 302/307 | MOVED TEMPORARILY | Temporarily redirect |
Error codes - Client side
| Status Code | Short | Description |
|---|---|---|
| 400 | BAD REQUEST | Issue with input data/validation |
| 401 | UNAUTHORIZED | Authentication related issue |
| 403 | FORBIDDEN | Insufficient permissions |
| 404 | NOT FOUND | Page does not exist |
| 406 | CONFLICT | Known API error |
| 429 | TOO MANY REQUESTS | Request throttled |
Error codes - Server side
| Status Code | Short | Description |
|---|---|---|
| 500 | SERVER ERROR | Server side issue |
| 502 | BAD GATEWAY | Routing issue |
| 503 | SERVICE UNAVAILABLE | Server down |
| 504 | GATEWAY TIMEOUT | Request timeout |
Standard API errors
4xx errors
4xx errors are errors caused by the client side. The server will usually respond with a content body explaining in detail what went wrong with this request. These errors need to be handled on the client side by a manual review process or automatically by having a system in place that mitigates specific situations.
If a 400 is thrown, your request was not processed fully by the Scantrust API and needs to be resubmitted with changes applied.
400 - BAD REQUEST
A very common status that indicates the client has sent bad data.
- Invalid format (e.g. missing fields that are required, ...)
- Validations we have put in place for the expected data failed (e.g. an invalid object is referenced)
- Invalid data type (e.g. strings instead of integers, wrong date formats, ...)
Example of a standard validation error response:
{
"brand": [
"Brand is required."
],
"name": [
"Description must be at least 10 characters"
],
"sku": [
"SKU must be unique"
]
}
401 - UNAUTHORIZED
The user is either not logged in, or the authorization token has not been sent or is invalid. This usually indicates there is something wrong with the login process.
403 - FORBIDDEN
User is logged in, but their account's role does not allow them to call this api - i.e. they don't have permissions.
404 - NOT FOUND
The URL you requested does not exist. In some cases, the identifier of the object requested will be a part of the URL. A 404 can then be thrown if a specific requested object is not available in the current context as well (e.g. when dealing with multiple companies).
409 - CONFLICT
This error is generally used when the application needs to know a specific error (such as a query timeout) occurred, and already knows how to respond to it.
{
"error_code": "8000",
"error_message": "SQL Timeout"
}
...
429 - TOO MANY REQUESTS
Our rate limiting was triggered. If hitting this limit, you are most likely implementing something incorrectly. More information about rate limits can be found here API Rate Limits.
5xx errors
A server side issue occurred. These issues can not be fixed by the client and should be reported to Scantrust support. Any request sent will have to be processed again later so you should always log and retry later in this case.