Get started
Rate limits
Each API key can make 50 requests per second. The limit is the same on every plan, and responses tell you how much of it is left.
The limit
| Applies to | Limit | Notes |
|---|---|---|
| Single lookups | 50 requests per second, per key | Counted per key, so two keys do not share a window. |
| Bulk jobs | Not subject to the per-second limit | Rows are processed in the background. Submit the list once. |
If you need a higher sustained rate, contact us with your expected volume.
Headers
Every response carries the state of your limit.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per second for this key. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | When the current window resets. |
Retry-After | Sent with a 429. Seconds to wait before the next request. |
When you exceed it
The request is rejected with 429 and the rate_limited error code. Nothing ran, so nothing is charged.
Response headers
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
Retry-After: 1429 Too Many Requests
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait for the Retry-After interval."
},
"meta": {
"credits_used": 0,
"credits_remaining": 999,
"cached": false,
"request_id": "req_8f3a2c1e9b7d"
}
}Backing off
Wait for the Retry-After interval, add a little jitter so parallel workers do not retry together, and cap the number of attempts.
async function lookup(url, body, key, attempt = 0) {
const res = await fetch(url, {
method: "POST",
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
if (res.status === 429 && attempt < 5) {
const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000;
const jitter = Math.random() * 250;
await new Promise((r) => setTimeout(r, wait + jitter));
return lookup(url, body, key, attempt + 1);
}
return res.json();
}Staying under the limit
- For a list, use the bulk API instead of a tight loop. One job replaces thousands of requests.
- Give each service its own key so one busy worker cannot starve another.
- Deduplicate inputs before you send them, so you do not spend requests on values you already have.