Rate limits
How many requests your API keys may make, what the API answers when you go over, and how to retry.
Rate limits protect the database that every workspace shares. They count requests, whatever each request does. API calls are not billed per call.
The limits
| Limit | What it counts | Allowed |
|---|---|---|
| Per key | Requests made with one key | 600 in 60 seconds |
| Per workspace | Requests made with all of the workspace's keys together | 1,200 in 60 seconds |
| Refused keys | Requests from one IP address with keys in the right format that don't work: unknown, revoked or expired keys, or keys that stopped working. A malformed header or key gets 401 and isn't counted | 30 in 60 seconds |
- Every call counts against both its key's limit and its workspace's limit. When several keys are busy at once, they can reach the workspace's limit before any one of them reaches its own.
- One request counts once. A page of up to 1,000 items counts once, and so does a batch of up to 100 creates and updates.
- There are no daily caps and no points per request.
- People using the app don't use up your keys' limits.
Going over a limit
A request over any limit gets 429 RATE_LIMITED, with Retry-After set to 10 and Cache-Control: no-store. The request did not run, so nothing was written.
{ "error": { "code": "RATE_LIMITED" } }The answer doesn't say which limit you reached.
What to do
- Honor
Retry-After. Wait that many seconds before you send the request again. - Back off. If the next try is refused too, wait longer each time before you try again.
- Spread work over time. Send a steady flow of requests rather than bursts, and run large jobs in the background.
- Do more in each request. Write many items in one batch, and read up to 1,000 items a page when querying items.
- Read only what changed. To keep a copy of a board current, read the changes feed rather than every item again.
- Retry creates safely. Send an
Idempotency-Keywhen you create a board or an item, or send a batch, so a retry never makes a duplicate. Other creates, such as a group's, don't read it. See Requests.
When a write is busy
A write can also answer 503 UNAVAILABLE when others changed the same thing at the same moment and the write ran out of tries. Nothing was written. The answer has Retry-After set to 1: wait that many seconds, then send the request again.
{ "error": { "code": "UNAVAILABLE" } }A 503 stores nothing under its Idempotency-Key, so you can send it again with the same key.
How exact the limits are
Each Cloudflare location counts requests on its own, and the count is approximate. Requests that reach different locations are counted apart, and a 429 can come a little before or after the number in the table. Treat the limits as a ceiling to stay under, not as a quota to use up.