Select programming language for code examples

linkRate Limiting

Rate limits are enforced per-token and IP combination. Rate limits are put in place to protect our servers from extraneous load, whether from a bad actor, a bug in an integration, or a runaway script. We've tried to build our rate limiting system in a way that limits abuse while not limiting legitimate usage.

For client-side requests, i.e. those made when unauthenticated or using a user or license token, an IP address may make a maximum burst of 60 requests per 30 second window and 500 requests per 5 minute window. This allows for an average of 1 request/sec with short bursts of up to 3-5 requests/sec.

For server-side environments, i.e. requests authenticated with an admin, environment or product token, these limits are higher based on your server-side usage.

We may add additional rate limit windows in the future, which will be included within the X-RateLimit-Window header with a specific name, e.g. 30s.

If we see patterns of abuse, this limit may be lowered or the IP may be temporarily blacklisted. In rare cases of significant abuse, the IP may be permanently blacklisted from our API.

When rate limited, a 429 HTTP status code will be given. You can also check the returned HTTP headers of any API request to see your current rate limit status for the closest window:

Header Description
X-RateLimit-Window The current rate limiting window that is closest to being reached, percentage-wise.
X-RateLimit-Count The number of requests that have been performed within the current rate limit window.
X-RateLimit-Limit The maximum number of requests that the IP is permitted to make for the current window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
Retry-After Indicates how long, in seconds, to wait before making a new request. Only included when rate limited.

linkAvoiding the rate limiter

Sometimes, you may find yourself occasionally needing to send API requests in high volume, causing rate limiting errors. Here are a few things to try:

  1. Slow down. If you're sending a large sequence of requests, add a small delay of 1–200ms between each request and see if that improves things. This is especially important when paginating large datasets or creating resources in bulk.
  2. Add jitter. In cases where you're running a cron job or invoking requests at a set interval across multiple machines, adding in some "jitter" can help reduce a thundering herd problem. In this case, "jitter" can simply be random delay value of 10ms to 10m, to help spread out the licensing requests across time.
  3. Add caching. In order to reduce request volume, you can cache previous responses for a set duration, to avoid hitting the network with superfluous requests. You can store response signatures to verify cache integrity.
  4. Use a token pool. In some instances, it may be more feasible to issue additional tokens to support higher request volume. For example, if you were attempting to license a fleet of hundreds of machines which all shared the same IP, you may want to issue a pool of tokens instead of a single token.
  5. Obey the headers. If all else fails, you can look at the rate limiting headers above and derive a delay from the X-RateLimit-Reset header once your X-RateLimit-Remaining count falls below a certain threshold.

Looking for a more customized rate limit? Reach out to our support team and we can discuss a custom rate limit. From trusting your proxies to whitelisting IPs, we'll find a solution that will work with your requirements.

Most customized rate limits require an Ent tier or above.

Example response / 429 Too Many Requests

X-RateLimit-Window: 5m
X-RateLimit-Count: 501
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1490973281
Retry-After: 59
{
"errors": [
{
"title": "Too many requests",
"detail": "Throttle limit has been reached for your IP address.",
"code": "TOO_MANY_REQUESTS"
}
]
}