How to Reduce Notion API Rate Limit Hits With Request Batching

If you build integrations with the Notion API, you have likely encountered the 429 Too Many Requests error. This error occurs when your application exceeds the Notion API rate limit of 3 requests per second per integration. The root cause is sending individual API calls too quickly without coordination. This article explains how to use request batching to group multiple operations into fewer API calls, staying within rate limits and keeping your integration running smoothly.

Why Notion API Rate Limits Hit Your Integration

Notion enforces a rate limit of 3 requests per second per integration token. This limit applies to all endpoints including querying databases, reading pages, and appending blocks. When your integration sends requests faster than 3 per second, the API returns an HTTP 429 status code with a Retry-After header. The integration must wait the specified number of seconds before making another request. If it does not wait, Notion may temporarily block the integration for one minute.

The most common cause of hitting this limit is sending one API call per database row or per block. For example, a script that reads 100 rows from a database by calling Retrieve a page 100 times in a loop will exceed the limit within the first 3 calls. Similarly, appending 10 blocks to a page by calling Append block children 10 times wastes 9 of those 10 calls. Request batching solves this by combining multiple operations into a single HTTP request.

Methods to Batch Requests and Stay Within Limits

There are two main approaches to reduce the number of API calls your integration makes. The first is to use the Notion API endpoints that accept multiple items in a single request. The second is to implement a queue system that spaces out individual requests so they never exceed 3 per second.

Use the Append Block Children Endpoint With Multiple Blocks

The Append block children endpoint accepts an array of block objects in the children parameter. Instead of sending one request per block, you can send all blocks in one request. This is the most effective batching technique for writing content to a page.

1. Prepare the blocks array
   Build a JSON array containing all the block objects you want to append. Each block object must have a type and the corresponding block content.
2. Send a single POST request
   POST to /v1/blocks/{block_id}/children with the array in the children field. Do not send one request per block.
3. Check the response for errors
   The API returns an object with the appended blocks. If any block fails validation, the entire request fails. Validate all blocks before sending.

This method reduces 10 separate requests to 1 request. It works for up to 100 blocks per request. For larger payloads, split blocks into batches of 100.

Implement a Request Queue With Exponential Backoff

When you cannot batch operations into a single endpoint call, use a queue that spaces requests at 333-millisecond intervals. This ensures you never exceed 3 requests per second. Combine this with retry logic that respects the Retry-After header.

1. Create a queue object
   Store pending requests in a FIFO array. Each queue item contains the request method, URL, headers, and body.
2. Process one request every 333 milliseconds
   Use a timer or delay function that waits 333 ms between processing each queue item. This keeps the rate at 3 requests per second.
3. Handle 429 responses with retry
   If the API returns 429, read the Retry-After header value in seconds. Pause the queue for that duration plus 1 second. Then retry the failed request.
4. Log rate limit hits
   Record each 429 response with a timestamp. If you see multiple 429s, reduce the processing interval to 400 ms or more.

A queue with exponential backoff adapts to server load without manual intervention. It prevents bursts of requests that trigger the 429 error.

If Notion API Rate Limits Still Block Your Integration

Integration Gets Blocked for One Minute After a 429

When your integration receives a 429 response and does not wait the full Retry-After duration, Notion blocks all subsequent requests for 60 seconds. To fix this, implement strict retry logic that pauses all requests for the Retry-After value plus 2 seconds. Do not process any queue items during this cooldown period.

Database Query Returns Incomplete Results

The Query a database endpoint supports pagination with a page_size parameter up to 100. Instead of calling Query for each page of results, set page_size to 100 and use the next_cursor to fetch remaining rows. This reduces the number of calls from N pages to N divided by 100.

Batch Request Fails Due to One Invalid Block

When you send multiple blocks in one Append block children request, the entire request fails if even one block is invalid. Validate each block object before adding it to the array. Check that required fields like type, text content, and URL are present and correctly formatted. Use the Notion API reference to confirm the exact schema for each block type.

Notion API Request Patterns: Batch vs Single Request

Item	Batch Request	Single Request
Endpoint used	Append block children with array	Append block children one block per call
Requests for 100 blocks	1 request	100 requests
Time to complete	~350 ms	~33 seconds (with 333 ms delay between calls)
Rate limit risk	Low — stays under 3 req/s	High — exceeds limit in first second
Error handling	Entire batch fails on one invalid block	Only the failed block fails

Request batching is the most effective method to reduce API calls and avoid rate limits. Use it for all write operations that involve multiple blocks or database rows.

You can now reduce Notion API rate limit hits by batching block appends and implementing a request queue with exponential backoff. Start by converting any loop that calls Append block children into a single request with an array of blocks. For database queries, set page_size to 100 and use next_cursor. An advanced tip: use the Retrieve a database endpoint to fetch the entire schema once and cache it locally, eliminating repeated schema reads that count against your rate limit.