Limits and quota
Values
| Limit | Default | Applies to |
|---|---|---|
| Per key | 60 requests per minute | each API key |
| Per organization | 120 requests per minute | all keys of the organization combined |
| Monthly quota | 50,000 requests per month | the organization |
| Per IP address | 300 requests per minute | any request, before the key is checked |
| Items per page | 50 (default), up to 100 | lists |
| Body size | 256 KB | POST and PATCH |
The values in force for your organization show up in the panel and in the /v1/me route. If you need higher limits, contact support.
The monthly quota
- The quota resets on the 1st of each month, at 00:00 UTC.
- Unused quota does not carry over to the next month.
- The owner and admins get an email when the organization uses 80% and 100% of the quota.
What counts against the quota
Each authenticated request that gets processed counts 1, read or write, including those that end in an error because of invalid data or a missing scope (403 insufficient_scope, 404, 409, 412, 422) and 304 responses.
Not counted:
- requests refused by a limit or the quota (
429); - requests without a valid key (
401); - requests refused for lack of access, subscription or terms acceptance (
402and the access403s:api_access_not_enabled,api_access_suspended,workspace_not_eligible,terms_not_accepted); - Validades failures (
5xx).
Limit headers
Every authenticated response tells where the limits stand:
| Header | Meaning |
|---|---|
RateLimit-Limit | requests allowed per minute for the key |
RateLimit-Remaining | requests left in the current minute |
RateLimit-Reset | seconds until the per-minute limit resets |
X-Quota-Limit | monthly quota of the organization |
X-Quota-Remaining | requests left this month |
X-Quota-Reset | when the quota resets (ISO 8601) |
429 error
code | When |
|---|---|
rate_limited | per-minute limit of the key, the organization or the IP |
quota_exceeded | monthly quota used up |
The response carries the Retry-After header with the seconds to wait. Respect it before trying again.
HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/json; charset=utf-8
{
"error": {
"code": "rate_limited",
"internal_code": 106,
"message": "Rate limit of 60 requests per minute for this API key exceeded. Try again in 18s.",
"request_id": "req_01JC…"
}
}
Best practices
- Respect
Retry-Afterand, for other temporary failures (5xx, network), retry with growing intervals (for example 1 s, 2 s, 4 s, 8 s), with a maximum number of attempts. - Fetch only what changed with
updated_sinceand/v1/deletions, instead of downloading everything every time. See Pagination and sync. - Use
limit=100in lists to spend fewer requests. - Use
include=batchesinGET /v1/products/{id}to get the product and its batches in a single request. - Use
If-None-Matchwhen fetching an item you already have: if nothing changed, the response is a304with no body. - Spread scheduled jobs across the minute instead of firing everything at second zero.