Rate Limiting

The Candis API now documents its rate limits on every endpoint and returns a consistent, machine-readable response when a limit is exceeded. Two independent limits apply: a request limit on every endpoint, and a record limit on core data import endpoints.

What's included

Request limit: Up to 500 requests per minute per organization and 2,500 per minute per holding, counted regardless of their contents. This limit applies to every Candis API endpoint.

Record limit: Core data import endpoints are additionally metered by the number of records in the request body. Contacts allow 600 records per minute per organization (burst 1,000); all other core data types allow 3,000 (burst 5,000). Holdings have higher shared allowances. A request may carry at most 100 records.

Consistent Retry-After header: Every 429 Too Many Requests response now carries a standard Retry-After header giving the whole number of seconds to wait, so a single retry handler works for both limits.

Machine-readable cause: The 429 body includes a limit field (request or record) identifying which limit was exceeded and a scope field (organization or holding) identifying whose allowance was exhausted, so you no longer need to parse the message text.

Live usage headers: Successful responses report the current request-limit state in X-RateLimit-Limit-organization, X-RateLimit-Remaining-organization and X-RateLimit-Reset-organization headers (with -holding counterparts inside a holding). X-RateLimit-Reset is the number of seconds until the window resets.

Recommended integration

Pace against the Retry-After header rather than hard-coding the published limits, which are standard values and may be adjusted per environment. A retry submitted before the stated interval has elapsed is rejected again, so fixed exponential backoff is neither required nor helpful.

Full details, worked examples, and effective throughput by batch size are on the Rate Limiting Policy page. The 429 response is documented on each endpoint in the API Reference.