Errors

When a request fails, the HTTP status says what kind of failure it was, and the body always has the same shape:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid upload.",
    "details": ["size: the file size in bytes is required."]
  }
}

• code is stable: branch on it.
• message is English text for people (for your logs). It may change; don’t match on it.
• details lists each problem, as path: message, for validation errors; it is empty otherwise.

HTTP	code	When	Retry?
400	validation_error	Invalid or unknown fields. details names each one.	No: fix the request.
401	unauthorized	The API key is missing, invalid or revoked.	No.
402	quota_exceeded	Your plan doesn’t allow it: the month’s minutes are used up, or the file is over the plan’s maximum size.	After upgrading, or next month.
402	insufficient_balance	Your balance is used up: the month’s included credit and your prepaid credit. Jobs already running finish.	After topping up, or when the month’s credit renews.
403	forbidden	Valid credentials that may not do this, such as managing API keys or webhook endpoints with an API key (those are done in the dashboard).	No.
403	module_not_in_plan	Your plan doesn’t include the module the route belongs to (transcoding…). Your organization’s modules are in GET /v1/organization, as modules.	After the module is added to your plan.
403	organization_suspended	Your organization is suspended, so nothing can be done on its behalf. Your dashboard says who to write to.	After it is restored.
404	not_found	The resource doesn’t exist in your organization, or the route doesn’t exist.	No.
409	conflict	Its state doesn’t allow it: canceling a finished job, retrying a job whose uploaded source has expired, an Idempotency-Key reused with another body.	No.
429	—	Too many requests. Sent by the gateway in front of the API, so its body may differ.	Yes, after a pause.
500	internal_error	Ours.	Yes; tell us if it persists.
503	service_unavailable	Momentarily unavailable.	Yes, after a few seconds.

Retrying safely

Retry 429, 500, 503 and network failures with exponential backoff (1 s, 2 s, 4 s… up to a minute or so). Reading is always safe to repeat. To make creating a job safe to repeat, send an Idempotency-Key with it: a repeated request with the same key returns the job created the first time instead of a second one.

A job that fails after it was created is a different thing: it has its own error, explained in When a job fails.