Rate limits - Qomon API Hub

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 /contacts
PATCH /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.

Response headers

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

When the API rejects a request with 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.

​How rate limiting works

​Expensive endpoints

​Response headers

​Example

Best practices

How rate limiting works

Expensive endpoints

Response headers

Example