Rate Limits

Rate limits depend on your plan. Unless your plan says otherwise, the default limit is 1 request per second. Limits apply per API key and per endpoint.

Rate-Limit Headers

Responses tell you where you stand:

Header Meaning
ratelimit-limit Requests allowed in the current window
ratelimit-remaining Requests left in the current window
ratelimit-reset Seconds until the window resets
x-ratelimit-limit-second The limit of the per-second window configured on your plan
x-ratelimit-limit-minute The limit of the per-minute window configured on your plan
x-ratelimit-limit-hour The limit of the per-hour window configured on your plan
x-ratelimit-remaining-second Requests left in the per-second window
x-ratelimit-remaining-minute Requests left in the per-minute window
x-ratelimit-remaining-hour Requests left in the per-hour window

The header values in the saved examples on this site come from the key that recorded them. Your plan's limits can differ, so read the headers of your own responses.

When You Go Over

When you exceed a limit, the API returns 429 Too Many Requests:

JSON
{
  "message": "API rate limit exceeded",
  "request_id": "9b1f3c5d7e9a1b3c5d7e9f1a3b5c7d9e"
}

Wait ratelimit-reset seconds before retrying. For bulk jobs, pace your requests to stay within ratelimit-limit.

Tip

Read ratelimit-remaining and ratelimit-reset from each response instead of hard-coding a delay: the limits configured on your plan can differ from the default.

Quota

Some endpoints (for example, lookups) also count against a quota on your plan. Each request uses one quota unit, regardless of how much data it returns. The platform shows your quota and how much of it is used under Settings → Organization Settings → API Usage (see Check API usage and quota in the Platform Guide).

A 429 response is shown in full, with its headers, on the Errors page.

Last updated