PUBLISHED PROVIDER LIMITS
Limits keep their provider-specific dimensions.
Connections have a plan-specific request budget per 60 seconds that can be spent in a burst. Data-source queries and the shared workspace pool impose separate limits.
Authentication: Internal integration token, OAuth access token
Primary scope: Connection, Plus A Shared Workspace Pool
Measured dimensions: Requests, Endpoint Requests, Workspace Capacity
Profile coverage: Plan-specific per-connection windows, the separate data-source query limit, shared workspace capacity, Retry-After, and overload and restricted-access responses. Payload size and property-specific request limits remain outside this profile.
Connection Rate
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Per-connection budget: other plans | 180 requests | Per 60 second | Connection | Plans other than Business and Enterprise The budget may be spent at any pace within the 60-second window. |
| Per-connection budget: Business and Enterprise | 600 requests | Per 60 second | Connection | Business or Enterprise workspace The budget may be spent at any pace within the 60-second window. |
Endpoint limits
| Limit | Value | Period | Scope | Conditions and variability |
|---|---|---|---|---|
| Data-source queries | 3 requests | Per second | Connection And Endpoint | Approximately three data-source queries per second per connection, separately from the general connection budget. |
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.
- HTTP 429 can identify a connection, workspace, or endpoint limit. HTTP 529 with service_overload is temporary overload. A 429 with public_api_request_blocked requires support rather than retries.
- Additional Data.rate Limit Reason: Machine-readable reason associated with the applied request limit.
- Additional Data.retry After: Wait in whole seconds, represented as a string when Retry-After is supplied.
RECOMMENDED HANDLING
Protect both the provider and your own queue.
- Honor Retry-After on retryable 429 and 529 responses; workspace waits can exceed one minute.
- Stop retrying public_api_request_blocked and contact Notion support.
- Track the plan-specific connection window, data-source query limit, and shared workspace budget separately.
- Use bounded exponential backoff with jitter; retry server errors only when the operation is safe to repeat.
VERIFICATION RECORD