Troubleshooting API errors

Each API has error codes corresponding to prerequisites. But some errors can appear in specific cases, and some errors are common to the different endpoints.

400 Bad Request

Something is wrong with your request (e.g. required attribute is missing). Check the response body for more information.

401 Unauthorized

This error appears in case the call is not correctly authenticated. Refresh the access token and retry the call. See Authorization to APIs

403 Forbidden

If you are authenticated, this error appears in case you do not have the sufficient permissions. Fix service account roles and retry. See Authorization to APIs

429 Too Many Requests

You are being rate limited. Check the Retry-After HTTP header to know when the call can be retried. However if this happen there is likely something wrong with your implementation, for instance make sure to reuse access tokens until they expire before requesting a new one.

500 Internal Server Error / 502 Bad Gateway / 503 Service Unavailable / 504 Gateway Timeout

In some cases with a correct request, the API may return one of these errors. As long as this is limited to a very small percentage of requests over a short period of time this is considered normal. As an example it is considered normal to have on occasion a 30 minute period with error rate under 1% of the sent traffic.

This usually occurs when the API is scaling up in case of a high volume of requests. This error indicates that the API is in preparation.

A general best practice for sending data over the internet is to set up a retry and/or back-off system in case of 500/502/503/504 errors.

A good starting point on the topic can be this article https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/

Timeouts

Connection timeouts and read-timeouts may occur occasionally. They are usually caused by network latency and are thus out of our control. Retry strategies are also the best way to deal with those errors. It is hard to advise on specific timeout values because they depends on the network latency between clients and servers. Try it out and choose what best fit your needs !

Error body example

{
    "code": {{Error number}},
    "message": {{Error message}},
    "details": []
}

The error number is specific to our API. The Error message contains additional information about the error encountered. It can also contain an error category specific to each API.