Rate Limiting

The Tive API utilizes rate limiting as a strategy to prevent network traffic spikes. Being able to put a cap on how often an action can be repeated within a given timeframe can help stop malicious activity and help prevent our servers from being overwhelmed.

For all endpoints, Tive allows 100 requests per minute per account per endpoint across all client credentials within an organization. This count is determined by the amount of requests utilizing the same x-tive-account-id.

In the cases where x-tive-account-id is not used for an endpoint, rate limits are determined by IP address instead. This is currently limited to the Accounts and Standardized Carriers endpoints.

There are numerous ways rate limiting can occur, but a common scenarios may include submitting a large number of requests in quick succession, such as bulk shipment creation or device configuration.

The following headers are returned on all responses to provide insight as to how close you are to being rate limited:

x-rate-limit-limit: 1m
x-rate-limit-remaining: 99 
x-rate-limit-reset: 2022-10-07T17:00:00.0000000Z 

x-rate-limit-remaining and x-rate-limit-limit outline the number of requests per minute you are allowed, while x-rate-limit-reset indicates the time when x-rate-limit-remaining will reset back to 100.

Retrying Requests

If you go over the request limit, the Tive API will respond with a 429 Too Many Requests error code.

The 429 error response will include a Retry-After header and error message indicating how long to wait (in seconds) before making a new request.

Retry-After Header

retry-after: 1064

Error Message

{
  "Type": "https://www.rfc-editor.org/rfc/rfc6585.html#section-4",
  "Title": "Too Many Requests",
  "Status": 429,
  "TraceId": "00-63ff2447aa60fbca42d5e99619c50dab-ad03398f6d6bc8b6-00",
  "Error": "You have exceeded rate limits for this endpoint with x-tive-account-id '2'. Maximum allowed: 1000 requests per 1 hour.  Please try again in 1064 seconds."
}