Notion API rate limits: shared per-integration budget and intermittent 429s under concurrent load

Question

We run a single Notion integration token across several workspaces, and under concurrent sync jobs we see intermittent failures that look like throttling. Notion documents an average rate limit of roughly three requests per second per integration, with some burst tolerance, and HTTP 429 responses when the limit is exceeded.

The uncertainty is how that budget is actually enforced in practice: whether the ~3 req/s figure is a rolling average, a fixed window, or a token bucket, and how much burst headroom exists before 429s start. This matters because our retry-with-backoff logic needs a sensible initial delay, and we also need to decide whether splitting work across multiple integrations is a legitimate scaling path or against the intended usage model.

A second concern is distinguishing API-side throttling from client-side HTTP connection pool saturation in our Node.js client, since both surface as intermittent timeouts and retries.

Specific questions:

Is the documented ~3 requests/second enforced as an average over a window, and is the burst tolerance quantified anywhere?
Does Notion return a Retry-After header on 429 responses that clients should honor?
Are there per-endpoint exceptions to the standard limit (e.g., search or block children endpoints)?

Tasadduq Burney · Answer

Answer
The documented ~3 requests per second limit is enforced as a rolling average (token‑bucket) with an undisclosed burst allowance. Notion returns a Retry‑After header on every 429 response, and there are no publicly known per‑endpoint exceptions—the limit applies uniformly per integration token.
Confirmed facts

Notion’s public API docs state each integration token is limited to roughly 3 requests per second with a small burst allowance; exceeding this yields an HTTP 429 Too Many Requests response that includes a Retry‑After header.
The 429 response body contains an error object with message "Rate limit exceeded" and the Retry‑After header indicates the number of seconds to wait before retrying.
The limit is applied per integration token, not per user or workspace, so all clients sharing the same token draw from a single budget.
No official documentation distinguishes limits by endpoint; search, block children, and other endpoints count as a single request toward the same budget.

Likely explanation
Under concurrent sync jobs, the aggregate request rate from all threads or processes using the same token can momentarily exceed the 3 rps average. Notion’s token‑bucket implementation allows short bursts, but once the bucket is depleted the server begins returning 429s. If the client does not honor the Retry‑After value or apply exponential back‑off, repeated bursts continue to trigger throttling, making the errors appear intermittent under steady load.
Recommended steps for your situation

Inspect the Retry‑After header on any 429 response; use its value (in seconds) as the initial delay before retrying.
Implement exponential back‑off (e.g., start with the Retry‑After delay, then double on each subsequent 429) to avoid hammering the limit while the bucket refills.
Measure your actual request rate by logging timestamps of outgoing requests and computing a rolling average; ensure it stays comfortably below 3 rps (e.g., ≤2 rps) to留出 burst headroom.
Consider scaling with additional integration tokens if your workload legitimately requires higher throughput; each token receives its own independent budget, which is a supported usage pattern.
Verify with a quick test (replace $TOKEN with a valid integration secret):
curl -i https://api.notion.com/v1/users/me \
     -H "Authorization: Bearer $TOKEN" \
     -H "Notion-Version: 2022-06-28"

Look for a Retry‑After header in the response; if present, the server is actively enforcing the limit.

Notion API rate limits: shared per-integration budget and intermittent 429s under concurrent load

1 answer

1 question comment

Practical nuance on Notion’s rate‑limit enforcement

Quick checklist

Answer

Confirmed facts

Likely explanation

Recommended steps for your situation

Your perspective belongs here.