Rate limits
How many calls a key may make a minute, which headers show what is left, and what to do on a 429.
This page explains the rate limit on API calls and how to stay inside it.
Each key may make 120 calls a minute. The limit is per key. Two keys have two limits.
Headers on every answer
Every answer carries two headers that follow the IETF RateLimit header fields (draft 11).
| Header | Example | Meaning |
|---|---|---|
RateLimit | "default";r=118;t=42 | How much of the current window is left: r is the calls remaining and t is the seconds until the window resets. |
RateLimit-Policy | "default";q=120;w=60 | The policy: q is the quota of 120 calls in a window w of 60 seconds. |
When you go over
A call over the limit is refused with 429 and the code rate_limited. The answer carries a Retry-After header with the seconds to wait.
{
"type": "https://docs.done.com/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"detail": "This key made 120 calls in the last minute.",
"fix": "Wait the number of seconds in Retry-After, then try again.",
"param": null,
"request_id": "req_7Tq2LmXa"
}Wait for Retry-After seconds, then try again. For calls that need an Idempotency-Key, retry with the same key. See Safe retries.
Staying inside the limit
- Use webhooks, not tight polling. A scoring run, a scout run and company research finish by webhook. If you do poll, poll every 10 to 30 seconds. See Webhooks.
- Ask for 100 items a page when you read a long list, so you need fewer calls. See Lists and pages.
- Send many people in one call. Scoring runs take up to 500 links. Adding people takes up to 500 at a time.
- Watch
RateLimit. Whenrgets close to 0, slow down until the window resets.
async function callWithBackoff(url, options) {
const response = await fetch(url, options);
if (response.status !== 429) return response;
const seconds = Number(response.headers.get('Retry-After')) || 5;
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
return callWithBackoff(url, options);
}Some kinds of work have their own daily limits. For example, a workspace may learn 20 voices a day. Past a daily limit, the call is refused with 429 daily_limit_reached.