Request throttling

The Brightpearl API is part of the overall Brightpearl Software-as-a-Service (SaaS) application. In common with the vast majority of SaaS applications, some parts of the Brightpearl infrastructure are shared between many Brightpearl accounts and users.

Like all SaaS applications, Brightpearl's computing capacity has limits, and as those limits are approached users will see the performance of the application begin to degrade. It is our responsibility to protect our customers from anyone who, deliberately or otherwise, tries to flood the Brightpearl API with so many requests that performance suffers.

How does Brightpearl implement throttling?

Brightpearl's throttling mechanism works slightly differently depending on whether you are connecting from a public app (LINK) or a private (APP).

If you are connecting from a private app, you will start to be throttled if the account you are connecting to receives more that 200 requests from private apps in the space of minute. This means that if many private apps are connected to an account, they share a pool of capacity and can cause each other to be throttled.

If you are connecting from a public app, the same 200 request-per-minute cap is in force, but each account/developer combination has its own pool of capacity. This means that activity from developer X's apps cannot cause developer Y's apps to be throttled.

In either case, when the 200 request per-minute cap is reached, subsequent requests in the rolling one minute period will start to receive HTTP 503 Too Busy responses.

How do I avoid hitting the request cap?

The only guaranteed way for you to avoid triggering the request cap is to implement request-rate limiting in your application. There are two ways of doing this:

Response headers

Every HTTP response from the Brightpearl API includes two headers.

brightpearl-requests-remaining The number of requests left in the current throttling period before you are throttled (integer 0-199)
brightpearl-next-throttle-period The time, in milliseconds, before the next throttling period begins.

Brute force rate-limiting

A simple, safe way to avoid hitting the request cap is to wait for 60/200 seconds (0.3 seconds) between every request you send to the Brightpearl API, but unless your application is always sending close to the maximum number of requests per minute, this could seriously degrade the performance of your application.

Rate tracking

The more efficient way is for your application to keep track of how many requests it has sent in the last rolling 60 second window and only wait if you detect that you are close to exceeding the limit.

How do I know which 'minute' I am in?

You can't with any certainty, as it is unlikely that your computer and Brightpearl's servers are completely synchronised. There is also the issue of timezones, as Brightpearl's servers currently run in different timezones depending on the accounts they are serving.

For reference, the algorithm we use to determine the current 'minute' is: current minute = system time in milliseconds / (60,000)

How long do I need to wait if I receive a 503?

Currently the only guaranteed way to make sure your next request does not receive a 503 is to wait for 60 seconds.

Do requests that receive a 503 get processed?

No, we discard requests that cause a 503. It will be safe to re-send your request as soon as you are out of the current minute.

Are there any other techniques that I can use to help avoid hitting the request cap?

Yes, we recommend:

  • Checking to see if the messages you use are designed to support multiple resources in a single message. Most GETs and some POSTs,PUTs and DELETEs allow you to work on multiple resources simultaneously.
  • Caching where possible - rather than re-sending GET messages, think if you can cache data. This is especially true of data that doesn't change very often, such as shipping methods.

Can I get the request limit increased for my account?

We currently have no plans to implement different request caps for different accounts.

Will the request cap ever be increased from 200?

Possibly, but our current analysis suggests this is a sensible, sustainable and fair number.

Have more questions? Submit a request