Notion API · api · fg-0458

Notion API returns 429 rate_limited during bulk imports at only a few requests per second

429 rate_limited

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

Each connection gets 180 requests per minute on most plans and 600 on Business and Enterprise, and every connection in a workspace also shares a separate workspace budget. Parallel workers use it up within seconds.

Fix

Throttle to about 3 requests per second per connection, wait the Retry-After seconds on 429 and 529, and stop retrying when the reason is public_api_request_blocked.

Apply

if (res.status === 429 || res.status === 529) {
  const body = await res.json();
  if (body.additional_data?.rate_limit_reason === "public_api_request_blocked") throw new Error("blocked");
  await new Promise(r => setTimeout(r, Number(res.headers.get("retry-after") ?? 1) * 1000));
}

Affects: Notion REST API, limits as published 2026-10 (180 per minute, 600 per minute on Business and Enterprise)

Sources

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp