PUBLISHED PROVIDER LIMITS
Limits keep their provider-specific dimensions.
Notion publishes an average per-connection rate and allows some bursts. Workspace-level capacity scales with the workspace plan and is shared across connections.
Authentication: Internal integration token, OAuth access token
Primary scope: Connection, Plus A Shared Workspace Pool
Measured dimensions: Requests, Workspace Capacity
Profile coverage: Per-connection request rates, shared workspace-level limits, Retry-After behavior, and documented overload signaling. Payload size and property-specific request limits remain outside this profile.
Connection Rate
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Per-connection request rate | 3 requests | Per second | Connection | The value is an average and some bursts above the average are allowed. |
Workspace Rate
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Workspace-level shared limit | Provider-specific | Provider-defined | Workspace | Workspace capacity scales with the workspace plan and is shared by all connections in the workspace. |
RESPONSE METADATA
Headers expose the applicable limit state.
Retry-AfterFormat: Integer Seconds- Integer seconds to wait before retrying.
WHEN A LIMIT IS EXCEEDED
Read the response before choosing a delay.
- Rate-limit responses can use HTTP 429 or HTTP 529.
- A 429 represents a request-rate limit. Notion can use 529 when the service is overloaded.
- Additional Data.rate Limit Reason: Machine-readable reason associated with the applied request limit.
RECOMMENDED HANDLING
Protect both the provider and your own queue.
- Honor Retry-After after a 429 response.
- Queue or spread integration work to smooth bursts.
- Treat shared workspace capacity separately from an individual connection's average rate.
- Use bounded exponential backoff for temporary overload responses.
VERIFICATION RECORD