API errors and limits

Every error comes back the same way: an HTTP status and a JSON body with a code to act on and a message to show or log. Act on the code: the message is written for a person and can be reworded.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Wait a moment and try again.",
    "retryAfter": 12
  }
}

Some errors carry more fields beside the code and the message. The table names them.

A plan refusal, when there are no videos left, too few for the length or the part is longer than the plan covers, carries the sentence the Studio shows for the same refusal. How videos are counted explains what a job uses, and Plans and limits what each plan includes.

• 60 requests a minute for each account, all its keys together, for every request but creating a job.
• 5 new jobs a minute for each account, shared with the Studio: creating a job counts against this limit instead.
• Past either one, the answer is RATE_LIMITED, with a Retry-After header and a retryAfter field giving the seconds to wait.

Wait the seconds it gives before sending again. A client that retries at once only stays limited.

At most 2 jobs made through the API can be queued or processing at once on one account. Sending a link, or starting a job made for a file, past that is refused with TOO_MANY_JOBS_IN_PROGRESS; send it again when one of them ends. A job still waiting for its file does not count, and nor do jobs started in the Studio.

The cap keeps one account from filling the queue every account shares. It limits the jobs under way, not how many an account makes: once one ends, the next can start.

A job that fails is not an error of the request. The request that made it succeeded, and the job's status turns to failed later, with its error. The error's kind names the failure, and its title and message are the ones the Studio shows:

Why a job failed says what to do about each one. A failed job counts nothing.

• Send a request that was refused again only once what its message names is fixed. The same request, unchanged, is refused the same way.
• After RATE_LIMITED, wait the seconds it gives. After INTERNAL_ERROR, or an answer that never came, wait a moment and send it again.
• Send a create again with the same Idempotency-Key, so a retry can never make a second job. Send a video through the API shows how.