---
title: Rate Limits
subtitle: >-
  Close API rate limit policies and how to handle 429 Too Many Requests
  responses.
slug: /api/overview/rate-limits
---

We enforce API call rate limits to protect our infrastructure from excessive
request rates, to keep Close fast and stable for everyone. These limits are high
enough that typical API workflows aren't affected. However, please do code your
integration to follow the rule below:

**If you receive a response status code of 429 (Too Many Requests), please
sleep/pause for the number of seconds specified by the `rate_reset` value before
making additional requests to that endpoint.** See below for the specific
response format.

Rate limits are enforced per endpoint group. Endpoint groups are used to provide
more granular control by grouping endpoint URL paths and methods (e.g. GET, PUT,
etc.) together. For instance, GETs to /api/v1/lead/ and POSTs/PUTs to
/api/v1/activity/ may be counted as two different API groups. This allows us to
offer a higher limit on lightweight requests than we would be able to on more
resource intensive request types.

API requests are limited at a per Organization level across all users' API keys.
We also enforce a lower rate limit per API key, which helps ensure that an
individual heavy integration doesn't cause other lightweight integrations (on
separate API keys) to get rate limited unnecessarily. The per Organization limit
is currently 3 times higher than individual API key rate limits, meaning that if
the API key rate limit maximum requests per second (RPS) is 20 RPS, the
organization wide limit would be 60 RPS for that same endpoint group. This
allows you to use 3 API keys at their maximum RPS and not hit the Organization
rate limit until you add a 4th key making additional requests. The 429 response
provides details to identify which limit and endpoint group was hit.

Most API responses will have the `ratelimit` header to provide rate limiting
statistics about the limit it's closest to hitting. Per the RFC spec, this
header will contain three values:

- `limit`: Request limit enforced for this endpoint, some endpoints may allow
  bursting over this limit
- `remaining`: Requests left in the enforcement window
- `reset`: Seconds remaining before this enforcement window ends (as a decimal).

For example, the full header might look like:

```
RateLimit: limit=100, remaining=50, reset=5
```

_Note: previously rate limit headers `x-rate-limit-limit`,
`x-rate-limit-remaining`, `x-rate-limit-reset` were included, however they have
been replaced by the above single `RateLimit` value._

Each `429` response is guaranteed to have the `ratelimit` header set as well as
the `retry-after` header as per RFC 7231 (equivalent to `x-rate-limit-reset`
rounded up to the next integer).

_Note: previously data was provided in the response body, however that
information should be gathered from the `RateLimit` header instead._

Some API endpoints may have stricter (unpredictable) rate limits and may trigger
a 429 even if the user agent places requests within the enforcement window. In
these scenarios only the `rate_reset` values and `retry-after` header may be
set.

Note: We recommend using the `rate_reset` value instead of the `retry-after`
header for a more accurate wait time.