Our APIs are designed to be highly available and robust, but you should write your software to deal with common temporary problems that happen with all types of APIs:
- unreliable network connectivity - particularly on mobile devices
- rate limiting
- temporary service problems
Your API-calling application should have a mechanism to automatically try again, possibly giving status information to your end user, before giving up. If your application fails on the first API failure, it could be quite brittle.
There are more and more client libraries that support this type of robustness, but, more than likely, you'll need to write your own code. If you do, consider making it part of a standard REST API calling library.
Your application should:
- examine the return status code
- decide on a pattern for trying again
- incorporate wait or loop code that delays for x milliseconds before trying again
Think carefully about how to handle this as retrying immediately could make the problem worse. Some examples of retry strategies are to use:
- exponential backoff
- overnight processing - this works well with longer retry intervals, such as doubling of the interval, that is, 1 second, 2 seconds, 4 seconds, and so on.
- if an end user is present, a lower initial retry interval, such as 200ms with a maximum retry interval of 3 seconds
Handling rate limit error code 429
See rate limits.
Retries in timeout or error situations
Your application should not assume that when a timeout or error occurs, it is an irrecoverable error - it should automatically retry.
For end user interactions, keeping your timeouts lower than 30 seconds (often the default timeout) helps with the responsiveness of your application. You might want to display a message to the end user that, “Connections are taking longer than normal…”.
5xx status codes can easily be transient problems, and as they are server side your application cannot do anything about them directly. This means you do not need to analyse the response. It is worth noting that some of our APIs provide a Retry-After header for 503 responses, which:
- gives you the number of seconds to wait before trying again, optimised for the specific API
- might contain a date-time, indicating that the service is down for maintenance, and when it will be available. For more details, see the HTTP-Date in RFC9110 for a definition
Whether you process this header or not, consider logging the values for analysis and using them to improve the next version of your software.
Although code 429 applies to rate limiting, consider retrying all 4xx status codes automatically.
Retries when updating data
If you are creating, updating or deleting data, the situation is more complex. We recommend to our API producers to expect a full retry, that is, to receive the entire request again including headers.
The API specification should specify any special behaviours to expect, for instance, Spine APIs tend to use a unique messageID to de-duplicate the requests.
Maximum polling attempts
Do not let your application keep retrying an API forever, but configure it to give up at an appropriate time. For any guidance on the maximum number of retries, see its API specification.
If there is no advice, select something that is a good balance for your situation. Where your application has end users, consider a much lower limit. For example, if your application has paused for as long as 10 seconds, many end users will have tried to refresh the page and start again.