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](https://www.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: ```typescript 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 ...