Guides: Rate limits and quotas
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. For this limit 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.
Only answered requests count toward the plan: a 2xx answer. A 404, a 400, a 413 or a 5xx costs nothing, and neither do the 401 and 429 answers, which are refused before anything is counted. The plan is checked before a request runs, so an answer that isn't 2xx is given back afterwards, usually within seconds.
GET /v1/usage tells you where the month stands, and it is free: it counts toward the per-minute limit, but not toward the plan. It answers periodStart and periodResetsOn (YYYY-MM-DD, UTC), requests (the whole account this month), includedRequests, hardLimit and remaining (both null on a plan with no cap), planName, planType, and keyRequests, the requests made with the key you sent.
We email you once when the month passes 80% of your plan's included requests, and once at 100%.
The Free plan has a hard monthly cap, counted per account across all its keys, deleted ones included. When it is used, the API answers 429 with the code QuotaExceeded and nothing is billed. The console shows what is left and when the count resets. The same happens on any other plan with a hard monthly cap. 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.
The Free plan's monthly lookups can need a verified card or phone number. An account without one gets a small number of starter lookups once, for the life of the account. When they are used, the 429 with QuotaExceeded also has verificationRequired: true and verifyUrl, the console page where you verify. No month resets the starter lookups, so there is no Retry-After. Verify the account, or upgrade.
The Free plan can also have a capacity for each day, shared by all Free accounts. When it is used, Free requests get a 429 with the code FreeCapacityExhausted until 00:00 UTC, and Retry-After counts the seconds to then. Your own quota is untouched, and paid plans aren't held to it.
See Pricing for what each plan includes.
Looking up many plates at once
POST /v1/vehicles/plates looks up 1 to 500 plates in one call. For the limit of 60 requests a minute per key, the whole call is one request, however many plates it holds. That is intended. It is the way to look up many plates without spending your minute on them.
The monthly quota counts differently: the call costs one request per plate it found. Plates that aren't valid, and plates no vehicle has, count nothing, and a plate sent twice counts once. The quota is checked for every distinct valid plate before any lookup, and the plates not found are given back after. If your account can't cover them all, the whole call is a 429 with the code QuotaExceeded, with no results and nothing counted. Send fewer plates, upgrade the plan, or wait for the reset.
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
429by readingRetry-After. Don't retry in a tight loop: those retries count toward the per-minute limit.
Need more than 60 requests a minute? Contact us.
Didn't find the answer? Email support@motorbay.app.