Notion API returns 429 rate_limited on bulk writes

Hi, it's BlueByte. If a script that creates or updates a lot of Notion pages has started failing with 429, you are not doing anything wrong — you are just sending faster than Notion will accept. Let's read what it is telling you, then slow the client down in three small ways so the errors stop.

What a 429 from Notion means

Your bulk job fails like this:

{ "object": "error", "status": 429, "code": "rate_limited",
  "message": "You have been rate limited." }

Under heavy load you may also see 529 with code service_overload. For your code they mean the same thing: back off. This is purely about pace — a bad payload or token returns different errors, so you do not need to touch either.

Why bulk writes cross the limit so fast

Notion limits each integration to an average of three requests per second, with short bursts allowed above that. The limit is per connection (integration token), so requests you fire in parallel from one token share a single budget — parallelism does not buy throughput, it reaches the ceiling faster. A tight loop of page creates, or a Promise.all over hundreds of items, trips it almost immediately.

Read the response before you change anything

Do not guess which limit you hit — the response tells you. A 429 carries a Retry-After header (seconds to wait) and an additional_data.rate_limit_reason field:

curl -si -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" -H "Content-Type: application/json" \
  -d @page.json | grep -i "retry-after\|rate_limit_reason"

If Retry-After is present, you are being throttled — not blocked by a bad token (401) or payload (400). If you never see it, log the full body; a validation_error there means the payload, not the rate.

Honor Retry-After, then throttle and batch

Three changes, cheapest first.

1. Respect Retry-After. On a 429, sleep exactly that long before retrying — never retry immediately.

async function notionFetch(url, options, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status === 429 && attempt < 5) {
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return notionFetch(url, options, attempt + 1);
  }
  return res;
}

2. Throttle below the limit. Send serially with a ~350 ms gap instead of in parallel; staying under three per second means you rarely see a 429 at all.

3. Batch the work. One request can append up to 100 block children within a 500 KB payload — group blocks into one call instead of one request per block.

A real case: importing 1,000 rows

Say you import 1,000 rows, each a page with ten blocks. Done naively that is 1,000 creates plus thousands of appends, and it 429s in seconds. Restructured, you create each page with its ten blocks in one request (well under the 100-block ceiling) and send those creates serially ~350 ms apart. The job now runs at roughly three pages per second with no 429s, and if one slips through, the Retry-After handler waits and continues instead of failing the import.

Confirm the job runs clean

Run it and watch the status codes. With throttling and Retry-After in place you should see a stream of 200s and, at most, the occasional 429 that recovers on its own — no un-retried 429s and no 529s.

How this differs from a payload or auth error

A 400 validation_error is a payload problem (too many blocks, a field over its limit) and retrying will not help. A 401 unauthorized is a token or sharing problem. Only 429/529 are about pace, and only those carry Retry-After. Put the throttle and retry in one shared client so no future code path can bypass it, and the next bulk job just works.