📊 API Limitations

The API uses a dynamic throttle which ensures everyone can enjoy the service and no one takes over by making many requests which will slow down responses to other users. Best practices suggest that you should always throttle any requests to API services.

When you request has been throttled you will receive a message like this:

409: "You must wait before accessing this url again."
The HTTP status you will get back is 409 Conflict.

HTTP/1.1 409 You must wait before accessing this url again.
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Retry-After: 1
Date: Wed, 21 May 2014 01:54:48 GMT
Content-Length: 0

📘

Why 409?

409 is technically the HTTP status code for "Conflict" but, for legacy reasons when interacting with other systems when the Nexudus API was built, we use the 409 status code instead of the more conventional 429.

Handling limits in code

Consider the following JavaScript code that takes advantage of the "Retry-After" response header to repeat an API request.

const getRequest = (url) => {
 $.ajax(url)
  .success((data) => {
      handleContentData(data);
 })
 .error((xhr, textStatus, errorThrown) => {
   if (xhr.status == 409) {
      var delay = request.getResponseHeader('Retry-After');
         if (delay) {
              //re-try again in "delay" seconds
              setTimeout(() => getRequest(url), delay * 1000);
          }
      } else {
          //handle other errors...
      }
  });
}

API Throttling Limits

You can use these limits as a general rule but keep always in mind the status code of the API responses rather than hard-coding these times in your code.