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

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)?