Errors & rate limits

Every error has the same JSON shape and a matching HTTP status. Every response carries an X-Request-Id; include it when you contact us.

Error shape

json

HTTP/1.1 400 Bad Request
X-Request-Id: req_6f1d0c2a9b8e4f7d8c6b5a4f3e2d1c0b

{
  "error": {
    "type": "invalid_request",
    "message": "font_size must be a number from 16 to 200",
    "param": "style.font_size"
  }
}

type	Status	Meaning
`invalid_request`	400, 422	A parameter is missing or wrong. `param` names it (e.g. `style.font_size`, `lines[2].words[0].end`). 422: well-formed but unusable, such as a source_url that isn't a media file link.
`unauthorized`	401	No API key, a malformed one, or a revoked key.
`forbidden`	403	Your plan doesn't include this, e.g. a 2160p export on Creator.
`not_found`	404	No such resource in your account (other accounts' ids are indistinguishable from missing ones).
`conflict`	409	The resource isn't in the right state: transcript not ready, a transcription already running, too many exports waiting.
`insufficient_credits`	402	Not enough credits for the work. Buy credits or upgrade, then retry.
`payload_too_large`	413	The file is larger than your plan's upload limit (or the request body exceeds 5 MB).
`rate_limited`	429	Too many requests for this key, or too many imports in progress. Wait for Retry-After seconds.
`internal`	500	Something failed on our side. Safe to retry; use an Idempotency-Key on POSTs.

Branch on error.type, not on the message text: messages are written for people and may change.

Rate limits

Each API key may make 60 requests per minute (a fixed one-minute window). Every response reports where you stand:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix time when the window resets
`Retry-After`	On 429 only: seconds to wait before retrying

Poll jobs and exports every 2–5 seconds at most, or use webhooks. Other limits: 10 active API keys and 10 webhook endpoints per account, 5 imports in progress per account, and 24 exports waiting per project.

Retrying safely

Retry 429 (after Retry-After), 500 and network errors with exponential backoff.
Don't retry other 4xx responses unchanged; fix the request first.
Send an Idempotency-Key on POSTs that create work, so a retry after a lost response never charges twice.