Reference
Rate limits
Check the six request limits, the rate headers and Retry-After so your client can pause correctly after a 429.
Requests are limited by IP address, key and campaign owner. Every limit uses a sliding window. When a request goes past a limit, it returns 429 before any campaign data is read.
Request limits
The checks below run in sequence. Once a check rejects a request, the checks after it do not run. Every check counts one request at the point it is reached, and that includes requests that fail pagination validation later or come back with a missing record.
| Check | Limit | Window | Shared by |
|---|---|---|---|
| Before authentication | 120 requests | 1 minute | Client IP address, on every request. |
| Invalid authentication | 20 attempts | 1 minute | Client IP address, only when authentication fails. |
| Key minute limit | 60 requests | 1 minute | One key. |
| Key day limit | 1,000 requests | 1 day | One key. |
| Owner minute limit | 120 requests | 1 minute | All keys belonging to the same campaign owner. |
| Owner day limit | 2,500 requests | 1 day | All keys belonging to the same campaign owner. |
Owner limits span every campaign. If a key is missing or invalid and this repeats, the invalid-authentication limit can be reached, and the response is 429 rather than 401.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790841660
Retry-After: 30
{"error":"Rate limit exceeded"}
Rate headers
Responses with the status 200, 404 and the handled 500 fetch errors include the three rate headers. For those responses, the headers describe the key minute limit of 60 requests. The remaining daily or owner budget is not shown.
| Field | Type | Description |
|---|---|---|
X-RateLimit-Limit |
integer string | The request limit for the reported window. |
X-RateLimit-Remaining |
integer string | Remaining requests for that window, never below zero. |
X-RateLimit-Reset |
integer string | Reset time reported by the limiter, as Unix epoch seconds rounded up. |
Retry-After |
integer string | Present on 429 only. Seconds until the reported reset, rounded up, with a minimum of 1. |
Each 429 response includes these headers plus Retry-After. Its rate headers describe whichever limit rejected the request, whether an IP, daily or owner limit.
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1790841660
Responses without rate headers
The handled 400, 401 and 503 responses include no X-RateLimit-* headers. A 400 pagination error still uses up budget, since the rate checks ran before it.
Retry-After appears only with 429. When you get 503, retry with growing delays as described in errors.
Pause after a 429
Wait for at least the number of seconds given in Retry-After before you send another request. A daily limit may call for a much longer pause than a minute limit. Lower the number of concurrent requests and store records your tool already holds.
Every list request and single-record request counts on its own. Fetch pages of up to 100 records, and pull details only when your tool needs the summary or description.