The Notion API gives each connection 600 requests per minute, about 10 per second, on Business and Enterprise workspaces, and 180 per minute, about 3 per second, on all other plans. Querying a data source is limited separately to about 3 requests per second. Go over a limit and you'll get HTTP 429 with a Retry-After header.
If you're syncing a CRM, a content calendar or a client portal into a workspace, the rate limit decides how fast that sync can run. There's more than one limit in play, and the headline number isn't always the one that stops you.
Request and payload caps in one place
| Item | Limit | Applies to |
|---|---|---|
| Requests per connection | 600 per minute (about 10 per second) | Business and Enterprise workspaces |
| Requests per connection | 180 per minute (about 3 per second) | All other plans |
| Data source queries | About 3 per second | Per connection |
| Payload size | 1000 block elements and 500KB | A single request |
| Rich text content | 2000 characters | text.content in one rich text object |
| Array size | 100 elements | Block arrays, multi-select options, relations, people |
All of these come from the request limits page in the Notion developer docs.
How the per-minute allowance works
Each connection gets a fixed allowance of requests per 60-second window, set by the workspace's plan. You can spend that allowance at any pace inside the window: spread evenly, or all in one burst. So a script that fires 180 requests in the first ten seconds and then waits is fine on the lower allowance, as long as it doesn't start the next batch before the window rolls over.
Three limits, not one
Here's what trips up a lot of integrations. The Notion developer docs, on the Request limits page, describe a separate per-workspace limit shared across every connection in that workspace. That means a connection can be rate limited even when it's comfortably inside its own allowance, because another tool in the same workspace is busy. The docs don't publish a number for this limit, and its Retry-After can be longer than a minute.
Data source queries have their own cap too, about 3 requests per second per connection. So if your job mostly reads a database, you'll be throttled at that speed, well below the 10 per second you might expect on Business or Enterprise.
Reading the error responses
- 429 with the rate_limited code: you've hit a limit. The Retry-After header gives a whole number of seconds to wait, and additional_data.rate_limit_reason tells you which limit it was.
- 529 with service_overload: the service is temporarily overloaded. Retry it the same way as a 429.
- 429 with public_api_request_blocked: don't retry. That connection's API access has been restricted.
The last one matters, because a blind retry loop will keep hammering a connection that's been blocked, and it won't recover on its own.
Building a sync that doesn't fall over
If you use the official JavaScript SDK, much of this is handled for you. It waits for Retry-After, capped at 60 seconds by default, and retries 429 and 529 responses automatically. If you write your own client, copy that behaviour: read Retry-After, wait at least that long, and add backoff on top.
A few habits keep you under the caps in the first place:
- Batch writes so each request carries as much as it can, within the 1000 block and 500KB payload ceilings.
- Split long text into chunks of 2000 characters or fewer, and arrays into groups of 100.
- Pace database reads at around 3 per second, whatever your plan.
- Log the rate_limit_reason on every 429, so you can tell a workspace-wide squeeze from your own connection running hot.
If you're shaping the databases that a sync writes into, this guide to setting up databases in your workspace helps you keep properties lean. And if you're deciding between polling and push, this explainer on APIs and webhooks covers the trade-off.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
How two other work apps throttle
Asana's API limits its search API to 60 requests per minute and allows 5 concurrent jobs per user on its duplication, instantiation and export endpoints. Trello's API allows 300 requests per 10 seconds per API key and 100 per 10 seconds per token, plus 100 requests per 900 seconds on /1/members/. If throughput is a deciding factor for your stack, my list of other all-in-one workspace apps is a good place to compare.
My advice for anyone writing a sync
Design for 3 requests per second and treat anything faster as a bonus. Respect Retry-After every time, retry 529s like 429s, and stop dead on public_api_request_blocked. Log which limit fired. When a 429 turns up while your own count looks fine, it's almost always the shared workspace limit, and the fix is to slow down, not to add more connections.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
What is the Notion API rate limit?
600 requests per minute per connection on Business and Enterprise workspaces, and 180 per minute on all other plans.
What happens when I exceed it?
You get HTTP 429 with a rate_limited code and a Retry-After header telling you how many seconds to wait.
Is querying a database limited separately?
Yes. Data source queries are limited to about 3 requests per second per connection.
Should I retry a 529?
Yes. A 529 means the service is temporarily overloaded; retry it like a 429, using Retry-After and backoff.
Do these limits apply per workspace too?
Yes. A shared per-workspace limit applies across all connections, so a 429 can still happen within your own limit.
