Understanding rate limiting

The v3 Customer API applies rate limiting to protect the service and ensure fair use. Limits are enforced per API key per project, so one integration's traffic never consumes another's allowance.

Limits by plan

API rate limits are applied per API key and are measured in requests per minute.
API access is available on the Business, Enterprise, and Trial plans. The standard limits for each plan are:

Rate-limit response headers

Every successful (2xx) response includes headers describing your current allowance:

When you exceed a limit, the response adds two more headers:

When a limit is exceeded

If you exceed a bucket's limit, the API responds with 429 Too Many Requests and an RFC 7807 problem+json body. The response sets X-RateLimit-Remaining to 0 and includes Retry-After.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42
Retry-After: 42

{
  "type": "https://apidocs.document360.io/apidocs/errors/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
  "trace_id": "req_abc123def456",
  "errors": [
    { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header." }
  ]
}

Best practices

• Honour the Retry-After header: wait the specified number of seconds before retrying.
• Use exponential backoff with jitter for repeated 429 responses instead of retrying immediately.
• Watch X-RateLimit-Remaining and slow down as it approaches 0, rather than waiting for a 429.
• Spread bulk work over time, and prefer the bulk endpoints (up to 100 items per request) to reduce the number of calls.
• Separate read-heavy and write-heavy workloads where possible, since they draw on different buckets.