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.

How limits are applied

Each caller has two independent limits — buckets — per project, based on the HTTP method:

Because the buckets are independent, heavy read traffic never exhausts your ability to write, and vice versa. Each bucket allows a maximum number of requests within a fixed time window; when the window elapses, the allowance resets.

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 — they draw on different buckets.