Rate limits and quotas

Two limits apply to your API requests:

• A rate limit of 10 requests per second per API key, so a script gone wrong can’t flood the API.
• A quota of API requests over the last 30 days, set by your plan, like 10,000 on the Free plan.

For Acme Studio, most API requests are key validations by Acme Photo: 2,000 active users, each validating their key about once a week, make about 9,000 requests in 30 days. The licenses their store creates add a few hundred.

Rate limit

Each API key can make 10 requests per second. The 11th request within a second answers 429 with rate_limited, and a Retry-After header telling how many seconds to wait:

// 429 Too Many Requests
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests with this API key: slow down and try again"
  }
}

• The limit is per key: two servers with their own key each get 10 requests per second.
• It only applies to API keys. Key validations by your applications, requests made with scoped tokens and requests made from the app aren’t rate limited.
• Refused requests don’t count toward your quota.

For Acme Studio, a nightly script importing 5,000 licenses sends one request every 100 ms, or waits for the Retry-After seconds whenever it gets a 429.

What counts toward the quota

Test products count like live ones: their validations and API requests use your quota too.

The 30-day window

Requests are counted per day, in UTC, and the quota covers the last 30 days, today included. Every day, the oldest day leaves the window: there’s no monthly reset, the count goes down as old days leave.

Open Usage in the sidebar to see your requests per day and per product. Requests that don’t target a product, like listing products, are counted apart.

When you go over the quota

1. At 75% and 90% of the quota, the owners and admins of your organization are emailed once.
2. Over the quota, they’re emailed that you have a grace period of 7 days. Everything keeps working.
3. Still over after 7 days, your organization is blocked: every API request with an API key or a token, and every key validation, answers 402 with plan_limit_exceeded. The owners and admins are emailed.

Going back under the limit, by upgrading or as old days leave the window, ends the grace period, or lifts the block. An upgrade applies right away; otherwise, at the next hourly check.

The app itself is never blocked: your team can still manage licenses, and upgrade.

The same rules apply to your active licenses: see when you go over a limit.

Reducing your requests

• Validate less often. A validation per launch is rarely needed: validate when the stored token gets close to expiring. See when to validate.
• Lengthen the max offline duration of your policies: a 1 week token needs about 4 validations a month per machine, a 1 day token 30. See max offline duration.
• Don’t retry refused validations in a loop: a refused validation counts, and will be refused again.
• Use the largest page size, 100, when listing, which also keeps you under the rate limit. See pagination.
• Filter instead of listing, like customers by email, rather than going through every page.
• Delete unused test products, or stop the CI jobs validating against them.

Edge cases

Requests refused for the block still count: an application retrying in a loop while blocked keeps the count up.

Several API keys share the same quota, which belongs to the organization, but each has its own rate limit.

A plan change applies its new quota right away, to the same 30 days of requests.