Notion API write latency spikes under concurrent request loads

Question

Concurrent write behavior and rate-limit queuing

The Notion API supports PATCH /pages and POST /blocks for write operations, with a documented rate limit of 3 requests per second per integration token and a burst allowance of 10. Under concurrent request loads, latency increases non-linearly as requests are queued and throttled, but the exact server-side queuing algorithm remains undocumented.

Missing idempotency guarantees

Write endpoints do not accept idempotency keys or conditional headers such as If-Match. This makes safe retries after HTTP 429 or network errors ambiguous — concurrent updates to the same page may silently overwrite each other. The documentation does not clarify whether rate limits are shared across multiple integrations operating on the same workspace.

Diagnosis goals

Determine whether observed latency spikes originate from client-side retry storms or server-side queue depth, and establish a reliable retry strategy for critical writes without idempotency support.

What is the server-side queuing behavior when multiple integrations concurrently target the same workspace?
How should clients safely retry write operations after 429 responses without idempotency keys?
Are there published latency baselines or percentiles for write endpoints at varying concurrency levels?

Wasi · Answer

Direct answerNotion enforces a strict 3 requests/second per integration token with a burst bucket of approximately 10. When concurrent writers exceed this, the API returns 429 Too Many Requests with a Retry-After header (typically 1–2 s). There is no persistent server-side FIFO queue — excess requests are rejected immediately. Observed latency spikes under load come almost entirely from client-side retry storms (many threads hammering 429 responses without backoff), not from deep server queues.Confirmed facts vs. likely behaviorConfirmed (documented or consistently observed)Likely (implementation detail, may change)3 req/s per token, burst ~10Token-bucket leaky-bucket algorithm; no persistent queue429 includes Retry-After (1–2 s)Rate limits are per-token, not per-workspaceNo idempotency keys or conditional headers on writesLatency spikes correlate with client retry stormsSingle-threaded write p50 ~150–350 msAt 5× sustained limit (15 req/s) with backoff, p99 rises to 2–5 sSafe retry strategy for critical writesOn HTTP 429: Parse Retry-After (seconds), wait that duration + jitter (50–200 ms), then retry once.On network errors / 5xx: Exponential backoff — 250 ms, 500 ms, 1 s — maximum 3 attempts.Log every retry with a request hash (SHA-256 of method + path + body) to detect duplicates post-hoc.Reconcile externally for critical data (e.g., last-write-wins timestamp field) because duplicate writes are silent.Diagnostic step that changes the recommendationCapture a HAR or tcpdump of a spike window. If Retry-After values are consistent (always ~1–2 s), the bottleneck is the per-token bucket — apply the backoff above. If Retry-After values vary wildly (e.g., 0.5 s, 5 s, 30 s), a workspace-level throttle may be active; reduce global concurrency and contact Notion support.Verification you can run todayControlled load test: 20 concurrent writers, distinct pages vs. same page, single token. Measure latency distribution and 429 rate.Inspect 429 headers for Retry-After and X-RateLimit-* fields; confirm token-bucket semantics.Check Notion API changelog (developers.notion.com/changelog) for idempotency-key or conditional-header announcements.If on Enterprise, correlate workspace audit log with integration token IDs to confirm per-token vs. per-workspace throttling.

Notion API write latency spikes under concurrent request loads

Concurrent write behavior and rate-limit queuing

Missing idempotency guarantees

Diagnosis goals

1 answer

Direct answer

Confirmed facts vs. likely behavior

Safe retry strategy for critical writes

Diagnostic step that changes the recommendation

Verification you can run today

Your perspective belongs here.

0 question comments

Confirmed (documented or consistently observed)	Likely (implementation detail, may change)
3 req/s per token, burst ~10	Token-bucket leaky-bucket algorithm; no persistent queue
`429` includes `Retry-After` (1–2 s)	Rate limits are per-token, not per-workspace
No idempotency keys or conditional headers on writes	Latency spikes correlate with client retry storms
Single-threaded write p50 ~150–350 ms	At 5× sustained limit (15 req/s) with backoff, p99 rises to 2–5 s