Agent Skills: Notion Rate Limits

Notion Rate Limits

Overview

The Notion API enforces 3 requests per second per integration token across all endpoints and tiers. Exceeding this returns HTTP 429 with a Retry-After header. Detect with isNotionClientError() + APIErrorCode.RateLimited, implement exponential backoff with jitter, and use queue-based throttling for high-throughput workloads.

Prerequisites

• @notionhq/client v2.x (TypeScript) or notion-client (Python)
• Integration token in NOTION_TOKEN from notion.so/my-integrations
• For queue patterns: p-queue v8+ (npm install p-queue)

Instructions

Step 1 — Detect Rate Limits and Apply Exponential Backoff

| Aspect | Value | |--------|-------| | Rate limit | 3 req/s per integration token (all tiers) | | Throttle response | HTTP 429 + Retry-After header (seconds) | | Scope | Per token, not per user or workspace | | Max block children | 1,000 per blocks.children.append | | Max page size | 100 results per paginated request |

The SDK retries 429 automatically (2 retries, 3 total attempts). For heavier workloads, use custom backoff that honors Retry-After and adds jitter to prevent thundering herd:

import { Client, isNotionClientError, APIErrorCode } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

async function withBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5, baseMs = 1000, maxMs = 32_000
): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try { return await fn(); }
    catch (err) {
      if (i === maxRetries) throw err;
      if (isNotionClientError(err) && err.code === APIErrorCode.RateLimited) {
        const wait = parseInt((err as any).headers?.['retry-after'] ?? '1', 10);
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }
      if (isNotionClientError(err) && err.status && err.status < 500) throw err;
      const delay = Math.min(baseMs * 2 ** i + Math.random() * 500, maxMs);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Exhausted retries');
}

Step 2 — Throttle with Queue-Based Request Management

Enforce the 3 req/s limit at the application level instead of relying on 429 responses:

import PQueue from 'p-queue';

const queue = new PQueue({
  concurrency: 3, interval: 1000, intervalCap: 3,
  carryoverConcurrencyCount: true,
});

async function throttled<T>(fn: () => Promise<T>): Promise<T> {
  return queue.add(fn, { throwOnTimeout: true }) as Promise<T>;
}

// Fetch 50 pages — automatically throttled to 3/s
const pages = await Promise.all(
  pageIds.map(id => throttled(() => notion.pages.retrieve({ page_id: id })))
);

Step 3 — Optimize Batch Operations to Minimize API Calls

Set page_size: 100 on every paginated query. Batch block appends into chunks of 100 instead of one-per-block. See batch patterns for full implementations with progress tracking.

// Paginate with max page size
async function queryAll(dbId: string, filter?: any) {
  const results = [];
  let cursor: string | undefined;
  do {
    const resp = await throttled(() => notion.databases.query({
      database_id: dbId, page_size: 100, start_cursor: cursor, filter,
    }));
    results.push(...resp.results);
    cursor = resp.has_more ? resp.next_cursor ?? undefined : undefined;
  } while (cursor);
  return results;
}

Output

• 429 errors retried automatically using Retry-After headers with jitter
• Queue-based throttling keeps requests at 3/s proactively
• Batch operations reduce total API calls via chunking and max page_size

Error Handling

| Scenario | Strategy | |----------|----------| | Single 429 | Honor Retry-After, retry once | | Repeated 429s | Exponential backoff + reduce concurrency | | Bulk ops (50+ items) | Queue with p-queue at 3 req/s | | Server error (5xx) | Backoff + retry up to 5 attempts | | Client error (4xx) | Do not retry — fix the request |

Examples

See full TypeScript and Python examples for database sync, bulk export, and rate limit monitoring patterns.

Resources

• Notion Request Limits — Official rate limit docs
• Notion Status Codes — 429 and error responses
• @notionhq/client — SDK with built-in retry
• p-queue — Promise queue with rate limiting

Next Steps

• See notion-common-errors for 401/403/404 troubleshooting alongside rate limits
• See notion-sdk-patterns for query patterns that work with these strategies
• See notion-search-retrieve for optimizing search to reduce API call volume