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, called 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, and the allowance resets when the window elapses. Depending on your plan, the read bucket allows either 120 or 200 requests per minute, and the write bucket allows either 60 or 100 requests per minute. Your exact limit for a given request is also returned in the X-RateLimit-Limit header of every response.

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.