Usage & Rate Limits
ShipEngine limits certain API usage to maximize stability and performance. Users who send too many requests in quick succession will receive a
429 Too Many Requests error response.
In addition, third-party APIs (such as carriers, insurance providers, or marketplaces) may impose their own rate limits. So if you get a rate limit error, then be sure to check the
error_source field to determine whether it's from ShipEngine or a third-party.
By default, ShipEngine allows you to send up to 200 requests per minute. If you need a higher limit, please submit a support ticket with the details of what you need. We may be able to increase your rate limit, or we may be able to suggest alternative ways to achieve your goals with fewer or less-frequent requests.
Handling Limits Gracefully
Requests exceeding the rate limit will receive a
429 Too Many Requests error response. The response will also include a
Retry-After header, which specifies the number of seconds to wait until your next request can be processed. With this information, you can implement retry logic as a way to gracefully handle rate limits.
Keep in mind that rate limits apply to all requests, so it would be wise to implement any retry logic at a global level. Otherwise, many requests sent around the same time will all be rate-limited and will all retry at the same time, which will cause many of them to be rate limited again.
The most common cause of rate limit errors is bulk processing, such as validating hundreds of addresses, creating hundreds of labels, or calculating rates for hundreds of shipments at the same time. Fortunately, ShipEngine provides bulk API endpoints for these use cases, which allow you to perform hundreds or thousands of operations with a single API request.
Learn more about bulk operations here:
- Batch label creation
- Calculate rates for multiple shipments
- Validate multiple addresses
- Create multiple shipments
- Subscribe to tracking webhooks
- Import orders
If you have automated tests for your code, and those tests make ShipEngine API calls, then you may experience sporadic test failure due to rate limits. This will occur even if your tests use sandbox API keys, since our sandbox environment has lower rate limits for some API endpoints.
Instead, we recommend building your ShipEngine integration in such a way that you can substitute a mock for testing purposes. Using a mock gives you more reliable behavior and allows you to test for various error conditions as well as successful responses. Mocks can also make your tests faster, since there won't be any network latency (unless you specifically simulate latency in the mock).