Rate Limiting
Workspace and API-key limits, usage metering, and customer-visible retry guidance for server integrations.
Section
16 / 27
Live API examples
Jump from the docs to real public pages that use the same read models.
Endpoints
/v1/results/latestCounts as one production request for the API key.
/v1/results/historyCounts as one production request; keep date ranges bounded.
/v1/statusPublic, unmetered compact feed-health summary.
How limits are applied
Free Beta daily and calendar-month hard limits are enforced for the whole workspace. Every active key in that workspace shares the same counters, so creating or rotating a key does not increase capacity. Legacy customer plans may also apply a key-level daily ceiling. Each authenticated protected /v1 request atomically reserves quota before the handler runs. Sandbox keys do not count against workspace quota; they use a separate per-client sliding-window abuse limit.
Successful response headers
Successful protected responses include daily X-RateLimit-* and RateLimit-* headers. Free Beta responses also include X-RateLimit-Month-Limit, X-RateLimit-Month-Remaining, and X-RateLimit-Month-Reset. API responses include X-Request-Id; clients may send X-Request-Id or X-Correlation-Id to join their logs with support evidence. Reset timestamps use UTC.
HTTP/1.1 200 OK X-Request-Id: req_01JZ4XQ6Z6Q7R3Q9B5Y8M2K4T1 X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 2994 X-RateLimit-Reset: 2026-05-27T00:00:00.000Z RateLimit-Limit: 3000 RateLimit-Remaining: 2994 RateLimit-Reset: 2026-05-27T00:00:00.000Z X-RateLimit-Month-Limit: 90000 X-RateLimit-Month-Remaining: 89874 X-RateLimit-Month-Reset: 2026-06-01T00:00:00.000Z
When a limit is exceeded
The API returns HTTP 429 when a quota is exhausted, HTTP 503 RATE_LIMIT_UNAVAILABLE when enforcement cannot make a safe decision, and HTTP 503 FEED_SNAPSHOT_UNAVAILABLE when no trusted result snapshot can be read. Protected OpenAPI operations document the shared 401, 403, 429, and 503 contract so generated SDKs can distinguish auth, scope, quota, and temporary data-plane failures. The error evidence identifies whether the exhausted window is the UTC day, UTC month, or a sliding window. Honor Retry-After instead of retrying in a tight loop.
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-27T00:00:00.000Z
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Daily API key request limit has been reached.",
"rate_limit": {
"scope": "api_key",
"window": "utc_day",
"limit": 3000,
"used": 3000,
"remaining": 0,
"reset_at": "2026-05-27T00:00:00.000Z",
"retry_after_seconds": 3600,
"hint": "Pause this API key until reset_at or raise the key daily limit in account API key settings."
}
}
}Usage reporting
The authenticated account shows daily totals and bounded request drill-downs by endpoint, status, client IP, latency, and filters. Sensitive values are redacted, and large request bodies are not retained for usage reporting.
API documentation FAQ
Short answers for teams using rate limiting in production integrations.
How do I know why a request was limited?
A limited request returns HTTP 429, RATE_LIMIT_EXCEEDED, Retry-After, and error.rate_limit with scope, window, limit, used, remaining, reset_at when available, retry_after_seconds, and a remediation hint. Free Beta responses identify workspace scope and expose both daily and calendar-month remaining values. Usage is visible in the customer account.
Should clients retry immediately after 429?
No. Clients should wait for Retry-After or the reset timestamp and should reduce polling frequency or cache stable catalog responses. Additional Free Beta keys do not increase workspace capacity.
Next: Get countries