We recommend that you implement our Retry Policy and KeepAlive Best Practices

API error codes and retry recommendation

In addition to the table above, in order to make sure the application can recover from more than 3 consecutive failed requests, as in the case of a service incident or a maintenance activity with a few minutes of downtime, another retry should be introduced for login/socket close/etc.

The retry should be with a longer interval than the previous one, for example every 2 minutes, or you can use Exponential Backoff. This means that the application waits a short time before the first retry, and then exponentially increases times between each subsequent retry. For example, it may retry the operation after 2 minutes, 4 minutes, 8 minutes, and so on.

An example for Exponential Backoff retry in JavaScript can be found here.

Too short intervals or too many retries can have an adverse effect on the target resource or service. This may prevent the resource or service from recovering from its overloaded state, and it will continue to block or refuse requests. This results in a vicious cycle where more and more requests are sent to the resource or service, and consequently its ability to recover is further reduced. Therefore, make sure you do not define intervals which are too short, to give the application time to recover and retry.

If you receive a 429 response code, this means that your request is being throttled due to rate-limiting. If you encounter this behavior, it is recommended that you provide a window of at least 1 second in between subsequent request retries (or 5 seconds for login requests). Clients who submit "bursty" traffic patterns to UMS may face rate-limiting issues, so it is recommended to smoothen traffic to a more distributed pattern whenever possible.

X-RateLimit-Limit: 120 // Limit for the period
X-RateLimit-Reset: 1701311916 // Reset Epoch for the preiod in Milliseconds
X-RateLimit-Remaining: 10 // Requests remaining for the peroid explanatory

The following are detailed 4xx response codes & their meanings: