Every Notion API limit, in one table

The Notion API now enforces two rate limits plus per-endpoint limits. The per-connection limit is a fixed budget per 60-second window that depends on the workspace's plan: 600 requests per minute (an average of 10 per second) on Business and Enterprise, and 180 requests per minute (an average of 3 per second) on all other plans. The budget can be spent evenly or in a single burst. A separate per-workspace limit is shared across all of a workspace's connections, so a request can be rate-limited even when its own connection is under budget. Querying a data source has its own limit of about 3 requests per second per connection.

Size limits are separate from rate limits. A request payload can hold at most 1,000 block elements and 500 KB. Rich text is capped at 2,000 characters per text object, arrays at 100 elements, and one append call at 100 block children with two levels of nesting. File uploads are capped at 5 MiB on Free workspaces and 5 GiB on paid ones.

There is also a new plan limit: from September 8, 2026, the REST API enforces the Free workspace block limit for multi-member Free workspaces. Values below come from Notion's developer reference, verified November 12, 2026.

Each connection (integration) has a budget per 60-second window. When it runs out, the Retry-After value is the time until the window resets, so it is at most 60 seconds. The per-workspace limit is shared and scaled to the plan, and its Retry-After can be longer than a minute. The 429 body includes additional_data.rate_limit_reason, which tells you which limit you hit. A connection's Health tab lists the limits it reached in the last 24 hours.

Size limits cap a single request, not how much a property can hold overall. A relation can contain far more than 100 pages, but you can set at most 100 in one request. Exceeding a size limit returns HTTP 400 validation_error with details in the message property. Notion recommends handling over-length values before sending, for example by checking URLs against the 2,000-character cap.

Writing page content goes through Append block children. One call accepts up to 100 children with up to two levels of nesting, so long documents need several calls. Reads are paginated: most list endpoints return 100 items per page at most. File uploads follow the same size limits as the Notion app, and files larger than 20 MiB must use multi-part upload. Free workspaces with more than one member also have a lifetime block cap that the API now enforces.

Rate limits: HTTP 429 with code rate_limited and message You have been rate limited. Please try again later. The response carries a Retry-After header (whole seconds), repeated in additional_data.retry_after, and additional_data.rate_limit_reason names the limit. A 529 service_overload means Notion is temporarily overloaded and should be retried the same way.

Size limits: HTTP 400 validation_error. The message property explains which field exceeded its limit, for example body failed validation: ....

Free workspace block limit: after the grace period, block-creating writes return HTTP 403 restricted_resource with This workspace has used all of its free blocks. Upgrade its plan in Notion to create more content. This is a plan limit, and retrying won't resolve it. Reads, deletes and edits that don't create blocks keep working.

Queue requests and honor Retry-After. Notion recommends routing calls through a queue so one burst doesn't consume the whole budget. Pause for at least the Retry-After value, then back off exponentially with jitter, and set a retry cap. The official JavaScript SDK does this automatically.

Write in bigger chunks. Append up to 100 blocks per call instead of one call per paragraph, and create a page with its initial children in one request.

Don't blindly retry writes that return 503. Check additional_data.retry_guidance, because the change may already have been saved.

Upgrade when the plan is the limit. Business and Enterprise raise the per-connection budget from 180 to 600 requests per minute. A paid plan removes the Free block cap and raises file uploads to 5 GiB.