How to Resolve Notion ‘API Rate Limit Exceeded’ Error

You see a red banner or a JSON response reading “API Rate Limit Exceeded” when using Notion integrations, automated workflows, or custom scripts. This error occurs when your workspace or integration sends too many API requests within a short time window. Notion enforces rate limits to protect server stability and ensure fair access for all users. This article explains the exact cause of the error, shows how to check your current usage, and provides step-by-step fixes to reduce request frequency and avoid the limit.

Why Notion Returns the API Rate Limit Exceeded Error

Notion’s API enforces a default rate limit of 3 requests per second (RPS) for most endpoints, with a burst allowance of up to 5 RPS for short periods. When an integration or script exceeds this threshold, the API returns HTTP status code 429 with the message “API Rate Limit Exceeded.” The limit applies per integration token, not per workspace. If you have multiple integrations using the same token, their combined requests count toward the limit. The rate limit resets after a rolling one-second window, meaning a single burst of 6 requests in one second will block further requests for that second.

Rate Limit Tiers by Plan

Notion adjusts the rate limit based on your workspace plan. Free and Plus plans share the standard 3 RPS limit. Business and Enterprise plans receive a higher limit of 5 RPS. Notion does not publish exact burst durations or per-minute caps, but internal testing shows that sustained traffic above 3 RPS for more than 5 seconds triggers the 429 response. The error message includes a Retry-After header in seconds, which tells you how long to wait before retrying.

Common Triggers for Rate Limit Errors

The error most often appears in three scenarios. First, a custom script loops through a large database and calls the API for each page without any delay. Second, a third-party automation tool like Zapier or Make sends multiple webhooks in quick succession. Third, a bulk import or export operation sends many write requests at once. In each case, the integration exceeds the 3 RPS threshold and receives the 429 error.

Steps to Diagnose and Fix the Rate Limit Error

The following steps help you identify the source of excessive requests and implement controls to stay within the limit. Perform them in order.

1. Check the Retry-After Header in the Error Response
   When you receive the 429 error, examine the HTTP response headers. The Retry-After value tells you the number of seconds to wait before sending the next request. For example, if Retry-After is 2, pause all requests for 2 seconds. Do not retry immediately without waiting, as this will continue to trigger the error.
2. View Your Integration’s Usage Dashboard
   Go to notion.so/my-integrations and select the integration token that is hitting the limit. The dashboard shows a graph of requests per second over the last 24 hours. Look for spikes above 3 RPS. If you see a consistent pattern of high traffic, you need to reduce the request rate.
3. Add a Fixed Delay Between Consecutive Requests
   In your script or automation tool, insert a sleep(1000) command (1000 milliseconds) between each API call. This ensures you never exceed 1 request per second, well below the 3 RPS limit. For Python, use time.sleep(1). For JavaScript, use setTimeout or await new Promise(r => setTimeout(r, 1000)). For Zapier, use the Delay action set to 1 second.
4. Use Batch Endpoints to Reduce Request Count
   Instead of fetching or updating pages one by one, use Notion’s batch endpoints where available. The Query a Database endpoint returns up to 100 pages per request. Use the start_cursor parameter to paginate through results. For updates, use the Update Page Properties endpoint with a list of page IDs in a single request. This reduces the total number of API calls.
5. Implement Exponential Backoff for Retries
   If your integration still receives occasional 429 errors, implement exponential backoff. After a 429 response, wait 1 second, then retry. If it fails again, wait 2 seconds, then 4 seconds, and so on, up to a maximum of 60 seconds. This prevents your retries from compounding the rate limit problem.
6. Upgrade Your Workspace Plan for a Higher Limit
   If your workflow genuinely requires more than 3 RPS, consider upgrading to a Business or Enterprise plan. These plans offer a 5 RPS limit. Note that Notion does not offer per-integration rate limit increases for Free or Plus plans. Contact Notion support if you need a custom rate limit for an enterprise integration.

If Notion Still Shows the Rate Limit Error After Fixes

Even after applying delays and batch operations, some users continue to see the 429 error. The following sub-sections address specific persistent scenarios.

Multiple Integrations Using the Same Token

If you have more than one script or automation using the same internal integration token, their combined requests count toward the limit. Create a separate internal integration for each distinct workflow. Go to notion.so/my-integrations, click New Integration, and generate a new token. Update each script to use its own token. Then add delays independently for each workflow.

Webhook Flood from Zapier or Make

Zapier or Make triggers that fire on every database change can send many requests in a short time. In Zapier, add a Delay step set to 2 seconds between the trigger and the Notion action. In Make, use the Sleep module set to 1000 milliseconds. Also, filter your trigger to only fire when specific conditions are met, such as a status change, instead of every edit.

Bulk Import Scripts That Loop Without Pausing

A script that imports hundreds of pages often sends requests as fast as possible. Modify the script to batch writes into groups of 10 pages, then wait 3 seconds between batches. For example, in Python, use for batch in chunks(pages, 10): and time.sleep(3) after each batch. This keeps the request rate under 3 RPS even during large imports.

Notion API Rate Limits by Plan: Free vs Plus vs Business vs Enterprise

Item	Free & Plus	Business & Enterprise
Requests per second (RPS)	3 RPS	5 RPS
Burst allowance	Up to 5 RPS for short bursts	Up to 8 RPS for short bursts
Retry-After header	Included in 429 response	Included in 429 response
Custom rate limit request	Not available	Contact support
Integration dashboard	Available	Available

Understanding these limits helps you choose the right plan for your workload. If your integration consistently needs more than 3 RPS, upgrading to Business or Enterprise is the only supported path. For most workflows, adding a 1-second delay between requests keeps you safely within the standard limit.

You can now diagnose the API Rate Limit Exceeded error by checking the Retry-After header and your integration dashboard. Add a 1000 ms delay between requests and use batch endpoints to reduce total call volume. For persistent issues, create separate integration tokens per workflow or upgrade your plan. As an advanced tip, use Notion’s Query a Database endpoint with a filter to retrieve only changed pages, which reduces unnecessary requests and keeps your integration efficient.