Rate limits

Each API key has a per-minute request budget based on its plan. The budget resets at the top of each minute.

Limits by plan

Response headers

Every successful authenticated response includes:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287

These appear only after authentication succeeds. A 401 response from a missing or invalid key does not carry them.

When you hit the limit

Exceeding the limit returns 429 rate_limited with a Retry-After header telling you how many seconds remain until the bucket resets.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  },
  "request_id": "req_..."
}

Wait at least Retry-After seconds. The next bucket starts at the top of the next minute, so later requests use the new minute's quota.

Handling rate limits

Recommended client behavior:

• Check X-RateLimit-Remaining on every response. When it drops below ~10% of your limit, start slowing down.
• On 429, sleep for Retry-After seconds and retry the same request once.
• For burst workloads, prefer bulk jobs over many sync requests. One POST /jobs with 500 video IDs is one rate-limit tick instead of 500.