How rate limiting works
The API uses a token bucket.
- Bucket capacity:
100 tokens
- Refill rate:
10 tokens per second
- Default request cost:
1 token
- Expensive request cost:
5 tokens
All requests authenticated against the space share the same bucket.
Expensive endpoints
These synchronous contact write endpoints cost 5 tokens per request:
POST /contactsPATCH /contacts/{id}
If you want the lower-cost write path, use POST /contacts/upsert. It keeps the default request cost of 1 token and is the recommended route for synchronization and mass updates.
Every rate-limited authenticated response includes these headers:
| Header | Meaning |
|---|
X-Ratelimit-Limit | Bucket shape in the format burst:100;rate:10.0 |
X-Ratelimit-Remaining | Tokens currently available in your bucket |
X-Ratelimit-Cost | Cost of the request that was just evaluated |
X-Ratelimit-Reset | Seconds until the bucket is fully refilled |
429 Too Many Requests, the response also includes:
| Header | Meaning |
|---|
Retry-After | Whole seconds to wait before retrying the same request |
Example
X-Ratelimit-Limit: burst:100;rate:10.0
X-Ratelimit-Remaining: 94
X-Ratelimit-Cost: 5
X-Ratelimit-Reset: 0.6
Best practices
- Prefer
POST /contacts/upsert for large imports and recurring syncs.
- Spread bursts when you send expensive synchronous contact writes.
- Read
Retry-After before retrying a 429 response.
Last modified on June 16, 2026
