Docs

Errors and status codes

Two kinds of failure, and the second one is the one that surprises people.

The call failed

Code	Means	Do
200	Accepted, or here is the job.	A queue call answers 200 with an id. The work has not run yet.
401	The token is missing, malformed or revoked.	Send Authorization: Bearer ytt_<your-token>. Create or replace the token at /account/api/.
404	No job or batch with that id on your account.	Check the id came from a queue call made with the same token.
422	The body did not validate.	`detail` is an array, one entry per field, each naming the field in `loc`.
429	Too many requests.	Back off and retry. Polling every 2 to 3 seconds stays well under it.

Every one of these carries a body. Most are a single string:

Most errors

{ "detail": "Your session expired. Please sign in again." }

A 422 is the exception. Its detail is an array with one entry per field that did not validate, and loc names the field, so you can point at the input rather than at the request:

422

{
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

The job failed, after a 200

Queueing answers 200 with an id before any work happens, so everything that can go wrong with the video itself, a private one, a live stream, one blocked in our region, out of minutes, arrives later. `state` is `failed` and `error` carries the reason. A failed job is not charged for. Fix the input and queue it again.

That means a caller that only checks the HTTP status of the queue call will think every job succeeded. Poll until the state is one of done or failed, and treat failed as your error path. Jobs and polling has the states.