---
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# 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](https://developer.candis.io/docs/rate-limiting-policy) page. The `429` response is documented on each endpoint in the API Reference.