Skip to main content

Limits and quota

Values​

LimitDefaultApplies to
Per key60 requests per minuteeach API key
Per organization120 requests per minuteall keys of the organization combined
Monthly quota50,000 requests per monththe organization
Per IP address300 requests per minuteany request, before the key is checked
Items per page50 (default), up to 100lists
Body size256 KBPOST 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 (402 and the access 403s: 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:

HeaderMeaning
RateLimit-Limitrequests allowed per minute for the key
RateLimit-Remainingrequests left in the current minute
RateLimit-Resetseconds until the per-minute limit resets
X-Quota-Limitmonthly quota of the organization
X-Quota-Remainingrequests left this month
X-Quota-Resetwhen the quota resets (ISO 8601)

429 error​

codeWhen
rate_limitedper-minute limit of the key, the organization or the IP
quota_exceededmonthly 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-After and, 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_since and /v1/deletions, instead of downloading everything every time. See Pagination and sync.
  • Use limit=100 in lists to spend fewer requests.
  • Use include=batches in GET /v1/products/{id} to get the product and its batches in a single request.
  • Use If-None-Match when fetching an item you already have: if nothing changed, the response is a 304 with no body.
  • Spread scheduled jobs across the minute instead of firing everything at second zero.