Rate limits and quotas

Two limits apply to every API key: a rate limit per minute, and your plan's monthly quota.

Per minute

Each API key may make 60 requests per minute per key. Every request counts, errors included. Requests are counted in fixed one-minute windows.

Going over the limit gets a 429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
X-Request-Id: 0HN7Q3C2V4K1M:00000001

{
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests this minute. Try again in 60 seconds.",
  "code": "RateLimitExceeded"
}

Retry-After is the number of seconds to wait before you retry. It's never more than 60.

Requests with no key, or with a value that isn't shaped like a key, are limited by IP address instead: 20 requests per minute. That limit is lower on purpose. A caller without a key has no reason to send many requests.

Monthly quota

Your plan sets how many requests are included each month. The count runs per calendar month in UTC and starts again on the 1st.

If a plan has a hard monthly cap and you reach it, the API answers 429 with the code QuotaExceeded. Retry-After then counts the seconds to 00:00 UTC on the 1st of next month, so waiting a minute won't help. Upgrade the plan, or wait for the reset.

See Pricing for what each plan includes.

Staying under the limits

• Spread requests out. 60 per minute is one a second.
• Cache what you've fetched. The data changes at most once a week, and reference data such as kinds and colors almost never. See Data source and freshness.
• Use search filters rather than paging through everything. See Pagination.
• Handle 429 by reading Retry-After. Don't retry in a tight loop: those retries count too.

Need more than 60 requests a minute? Contact us.