notion-rate-limits

name	notion-rate-limits
description	Manage Notion API rate limits with exponential backoff, queue-based throttling, and batch optimization. Use when hitting 429 errors, implementing retry logic, or optimizing API request throughput for Notion integrations. Trigger with "notion rate limit", "notion 429", "notion retry", "notion backoff", "notion throttling", "notion too many requests", "notion queue".
allowed-tools	Read, Write, Edit, Bash(npm:*), Glob, Grep
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion","rate-limiting","api","resilience"]
compatibility	Designed for Claude Code

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 = , baseMs = , maxMs = 
): <T> {
   ( i = ; i <= maxRetries; i++) {
     {   (); }
     (err) {
       (i === maxRetries)  err;
       ((err) && err. === .) {
         wait = ((err  ).?.[] ?? , );
          ( (r, wait * ));
        ;
      }
       ((err) && err. && err. < )  err;
       delay = .(baseMs *  ** i + .() * , maxMs);
        ( (r, delay));
    }
  }
    ();
}