Rate Limiting¶

CloudSync enforces rate limits to ensure fair usage and platform stability.

Default Limits¶

Plan	Requests/sec	Documents	Connections
Free	10	100	5
Pro	100	10,000	50
Business	1,000	100,000	500
Enterprise	Custom	Custom	Custom

Rate Limit Headers¶

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705056600

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Handling Rate Limits¶

When rate limited, the SDK raises RateLimitError:

from cloudsync.exceptions import RateLimitError

try:
    doc.set({"key": "value"})
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
    time.sleep(e.retry_after)

Automatic backoff¶

The SDK handles rate limits automatically by default:

client = CloudSyncClient(
    api_key="...",
    rate_limit_strategy="backoff",  # backoff | error | drop
)

Strategy	Behavior
`backoff`	Automatically waits and retries (default)
`error`	Raises `RateLimitError` immediately
`drop`	Silently drops the request

Burst Allowance¶

All plans include a burst allowance of 2x the base rate for up to 10 seconds.

For example, a Pro plan (100 req/s) can burst to 200 req/s for brief spikes.

Next: Migration Guide →