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