To maximize its stability, the Shipup REST API restricts the number of requests you can make over a period of time. This rate limiting is implemented using the leaky bucket algorithm, allowing a burst of requests to be done at once.
Using this algorithm, we allow 2 requests per second with a burst of 60 requests.
In other words, you will be able to make 120 requests per minute. If you are using our batched API, which accepts a maximum of 100 entities, you will therefore be able to push 12,000 orders per minute.
Basic example
Usage with the following context:
- Job that can push orders created in your system in the last 5 minutes
- The job has a retry mechanism to retry 3 times the job in case of errors
What you need to do to maxims the number of orders imported:
- Make the job pushing the orders in batches of 100, with the last batch being the rest of the orders which is lower than 100
- Wait 0.5 seconds between each call
With this procedure, you will be able to push up to 1200 orders per minute.
Importance of implementing a retry mechanism
While sending requests to the API, you can know the remaining call for the interval by checking the X-Shipup-Api-Call-Limit header in the API response.
When the limit is reached, an HTTP 429 error response is returned for the following requests, until the limited interval is reached.
You can retrieve the next time a request is allowed by checking the Retry-After header.
To make sure all of the data sent is correctly handled, it is greatly recommended to add monitoring to be alerted of requests exceeding the rate limits.
Advanced explanations on the leaky bucket mechanism
The main points to understand about the leaky bucket metaphor are as follows:
- Each account has access to a bucket. In our case, our bucket can hold 120 marbles.
- Each second, two marbles are removed from the bucket (if there are any). That way there’s always more room.
- Each API request requires you to toss a marble in the bucket.
- If the bucket gets full, you get an error and have to wait for more room to become available in the bucket.
This model ensures that accounts that manage API calls responsibly will always have room in their buckets to make a burst of requests if needed. For example, if you average 1 request (“marbles”) per second but suddenly need to make 30 requests all at once, you can still do so without hitting your rate limit.