Rate limiting

The Lightspeed Retail (X-Series) API is rate-limited, to prevent a single API consumer from adversely affecting others using the platform.
This rate limiting is applied to authorized API requests. The API's authorization endpoints have their own rate limiting settings, more information about this can be found on the authorization page.

Current limits

We have broken down the rate limits into the following request sources:

• Rate limit per retailer per application
  • e.g A request from a service or application that has integrated our API
• Rate limit per retailer for all users
  • e.g A request from a user for example in-store on a mobile device or browser

As different request sources are separately rate limited we ensure that your API integration (application) requests cannot rate limit any of your in store requests a user (user) might be making while making a payment and visa versa.

Currently, the default rate limit for all sources listed above is calculated based on how many registers your retailer has. We might adjust these limits in the future per source to ensure a good balance between our system performance and your retailer request needs.

The current limit is:

300 x <number of registers> + 50

For a store with a single register that will result in a limit of 350 requests. The rate limiter is currently based on a 5 minute (300 seconds) window. This represents slightly more than one request per second, per register.

How do I know what my current rate limit usage is?

We have introduced two new headers which are included in every response from our API for JSON based requests to give you this transparency.

• X-RateLimit-Limit (This header declares the limit based on your request)
• X-RateLimit-Remaining (This header declares how much you have left until you reach your limit)

Example headers:

  x-ratelimit-limit: 100
  x-ratelimit-remaining: 99

So for this example, we can say that you have 99 tokens left out of your limit of 100.

What happens when the limit is reached?

If you hit the rate limit, you’ll be unable to make any more API requests for that retailer until the limiter resets.
Below is an example of a response to a rate-limited request:

{
    "error": "Too Many Requests",
    "message": "Rate limiting enforced"
}

The “retry-after” information is provided via the Retry-After HTTP header.

For the header, Lightspeed Retail (X-Series) uses an 'HTTP date' format (RFC1123), for example:

Retry-After: Wed, 15 Jul 2020 15:04:05 GMT

Coping with Rate Limiting

The best way to deal with rate limiting is to process your Lightspeed Retail (X-Series) API requests in a queuing system.
You can then defer jobs that access the API, upon the first 429 response, until after the rate has been reset.
This approach has the advantage of using the API as fast as is possible, then pausing.

A less desirable solution is to pause/sleep any processes that use the API after each call;
this doesn’t respond as well to changes in the limits, nor to two processes using the API at once.
For these reasons, we strongly recommend a queue; most languages have many “deferred job” systems available.