Rate limiting

Requests are rate limited per user account, not per token. If you create separate tokens for different integrations, as recommended in Authentication, all of them draw from the same budget because they belong to the same user. Two limits apply at the same time: 300 requests per minute and a burst ceiling of 15 requests per second. Exceeding either one returns a 429 Too Many Requests response.

Limits may change without notice. If your integration needs a higher limit, reach out to our support team.

Rate limit headers

Successful (non-throttled) responses include headers describing your current rate limit status:

curl -i "https://api.contractorscloud.com/api/v1/users" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed per minute.
`X-RateLimit-Remaining`	The number of requests remaining in the current minute window.

Handling 429 responses

A 429 response returns a JSON body naming the error, with no rate limit headers at all:

{
  "message": "Slow down. Please wait at least one minute and try again."
}

Don’t build retry logic around a Retry-After or X-RateLimit-Reset header — the 429 response doesn’t include either. Instead, pause briefly and retry with exponential backoff: wait one second, then double the wait after each subsequent failure. If your integration sends requests in bursts, spread them out so you stay under 15 requests per second.

Reduce how many calls your integration makes: page through results with a larger page[size], and request only the relationships and attributes you actually need.

Getting Started

Reference

Rate limit headers

Handling 429 responses

​Rate limit headers

​Handling 429 responses

Rate limit headers

Handling 429 responses