Which Notion API rate limit strategies prevent production failures during high-load data synchronization?

Answer to the Question

Notion’s API returns a 429 Too Many Requests status when the integration exceeds the per‑integration limit (≈3 requests / second). The response includes a Retry-After header that tells the client how many seconds to wait before retrying. If the header is absent, a safe fallback is to apply exponential backoff starting at 1 second, doubling each retry up to a maximum of 60 seconds.

Recommended Retry Loop Pattern

1. Send the request. Include the required Notion-Version header and bearer token.
2. Check the status. If 200‑299, process the payload and reset any backoff counters.
3. Handle 429. Read Retry-After (seconds). If present, wait that exact duration plus a small random jitter (0–0.5× delay). If missing, use the exponential backoff value for the current attempt.
4. Limit retries. Cap the number of attempts (e.g., 5) to avoid infinite loops.
5. Reset after success. Clear the backoff counter so the next burst can resume at the base rate.

Optional Traffic Shaping

For integrations that issue many concurrent workers, a client‑side token‑bucket or leaky‑bucket limiter can shape outbound traffic to stay comfortably below the 3 rps ceiling. This reduces the chance of hitting the 429 threshold in the first place.

Key Points to Verify in Production

• Log each request’s Retry-After value and the actual wait time.
• Run a small load test (e.g., 5 rps) to confirm that the effective rate stabilizes near the limit without sustained 429s.
• Check that jitter spreads retry times across parallel workers, preventing a thundering herd.

Missing Diagnostic Detail

Do you know the target request‑rate you plan to maintain per integration? Knowing that number can help fine‑tune the maximum backoff value and the bucket size if you implement traffic shaping.