Rate limits

Each account has a per-minute request budget based on its plan. The public REST API and MCP endpoint share that counter, including MCP requests authenticated through OAuth. Website session requests have separate limits; sharing credits does not mean sharing every throttle.

Limits by plan

Response headers

Every authenticated response carries these headers, including error responses and the 429 itself:

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 limit 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 before retrying.

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 a per-minute 429, wait for Retry-After seconds and retry with the same Idempotency-Key. This throttle runs before idempotency and does not cache the rejection.
• After an explicit active-job-cap 429, wait for capacity, then submit with a new Idempotency-Key. That rejection is cached; the old key keeps replaying it even after a job finishes. For network failures or timeouts where the outcome is unknown, keep the original key so a retry cannot create a duplicate job.
• 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.