Rate limits
The API limits how many requests a key and an account can send each minute. Credits that the API spends also have daily limits. This page covers both, and what your code should do when it reaches one.
Requests per minute
The limit depends on what the call does. A call that only reads has the highest limit, a call that changes something has a lower one, and a call that spends credits has the lowest. A call that spends is never counted with the reads.
Each kind has two limits. One applies to a single API key, and the other applies to the whole account across all of its keys. A key that sends too much does not stop your other keys, and opening more keys does not raise the limit of the account. Limits do not depend on the IP address.
The window is one minute.
| Kind of call | Each key, a minute | Each account, a minute |
|---|---|---|
Calls that read (read) | 120 | 240 |
Calls that change something (write) | 60 | 120 |
Calls that spend (spend) | 10 | 20 |
Headers on every response
Every response tells you where you stand.
RateLimit-Limitis the limit for this kind of call.RateLimit-Remainingis how many requests are left in the current window.RateLimit-Resetis how many seconds are left in the window.
Read these headers and slow down before you reach zero.
When you reach the limit
The API answers 429 with the code RATE_LIMITED and a Retry-After header. Wait for that many seconds, then send the same request. If the request spends credits, send it with the same Idempotency-Key.
Daily limits
The API bonus and the plans have daily limits, for example on exports. When one is used up, the API answers 429 with the code DAILY_LIMIT_REACHED. This code is different from RATE_LIMITED. The limit does not pass in a few seconds, so do not retry. It resets at 00:00 UTC. Stop and tell the user.
API pricing gives the daily limits of each plan and of the API bonus.
Waiting on jobs
A request with ?wait= stays open while a job runs, so it is also limited. An account can keep a few of these waits open at once. When all of them are in use, a new wait does not start, and the answer is the same as for wait=0. It is a normal read and the call does not fail, so pause for a few seconds before you read the job again. Wait for long jobs has the numbers.
Errors and the limit
All errors and what to do about them are on the errors page. Look at error.code before you decide to wait or to stop.