Errors & Responses

Every error code, what caused it and what to do.

One shape for every error

Whatever went wrong, the body looks like this. Branch on code; the message may change, the codes won’t.

Error

{  "error": {    "code": "insufficient_balance",    "message": "Your API balance is too low for this call. Top up to continue."  }}

One exception: a malformed body

If a field fails the request’s own type checks (a string where a number belongs, say), you get 422 with a detail list instead of the shape above.

On the response

HTTP	Code	What it means
401	`unauthorized`	Missing, unknown or revoked key.
402	`insufficient_balance`	Your balance won't cover the estimated hold. Top up to continue.
400	`invalid_input`	A field failed validation, or a file_key doesn't start with api/.
400	`unsupported_format`	That file type isn't accepted.
400	`input_too_large`	Over the size limit for its type.
400	`capability_unavailable`	This capability is switched off right now.
404	`not_found`	No such job, or it isn't yours.
429	`rate_limited`	You're sending too fast. Back off and retry.
429	`at_capacity`	The platform is briefly full. Retry shortly.
502	`capacity_unavailable`	No capacity for a live session right now.
502	`capacity_warming`	Voice capacity is starting up. Retry in about a minute.
502 / 500	`internal_error`	Failed on our side. Nothing is charged; retry, and tell us if it keeps happening.

The capacity errors are 502, not 503

capacity_unavailable, capacity_warming and internal_error arrive as 502, and internal_error can also be a 500. If your retry logic keys on the status, treat both as retryable.

On a job

These arrive inside error on a job that finished as failed. The request that started the work succeeded; the work didn’t. A failed job is refunded in full.

Code on the job	What it means
`face_not_detected`	No face was found in the input.
`unsupported_format`	The file couldn't be decoded once work started.
`input_too_large`	Over a size or duration limit found during processing.
`content_rejected`	The input or the result failed a content check.
`processing_failed`	The render didn't complete.