Errors

The error envelope, every stable error code, and what your agent should do for each.

The envelope

Every /api/v1 error body has at least these keys (validation_error 422s add errors, the raw validation list):

{
  "detail": {
    "error_code": "insufficient_credits",
    "message": "Insufficient credits: ... Top up at https://www.cliphi.com/pricing.",
    "billed": false
  }
}

message is written to be relayed to a human verbatim. billed says whether money moved (always false on request errors).

Renders can also fail asynchronously: render_status: "failed" arrives inside a successful poll. Branch on fields, never on HTTP codes alone.

Error codes

Code	HTTP	Meaning / agent action
`missing_api_key`	401	No key sent. Message says where to create one.
`invalid_api_key`	401	Wrong or revoked key.
`invalid_url`	400	The URL is well-formed but not a usable video. Fix the input, do not retry unchanged. (A string that is not a URL at all fails earlier as 422 `validation_error`.)
`insufficient_credits`	402	Message includes balance, required amount, top-up link.
`video_too_long`	422	Over the length limit (up to 3 hours by default; the message states the current limit). With fast-ack this often surfaces as a failed poll instead.
`throttled`	429	Too many jobs; retry after the stated wait.
`maintenance`	503	Temporary; retry later.
`upstream_error`	varies	Source site refused the video; the upstream status is preserved. Often transient.
`job_not_found`	404	Unknown job id. (Another account's job is 403 `access_denied`, never 404.)
`access_denied`	403	The resource belongs to another account.
`moment_not_found`	404	Unknown moment id for this job.
`moment_not_ready`	409	Job still processing; poll first.
`source_expired`	409	Source files are kept 30 days; this one aged out. Resubmit the video.
`nothing_to_render`	409	16:9 with captions, title, description all off and no crop would equal the free preview.
`clip_too_long`	409	Moment exceeds the render length cap.
`render_in_progress`	409	Same render already running; poll instead.
`demo_unavailable`	404	Demo being refreshed; try later.
`not_found` / `method_not_allowed`	404/405	Wrong path or verb.
`http_error`	varies	Generic enveloped framework error.
`validation_error`	422	Request shape invalid; `errors` lists fields.
`internal_error`	500	Our side. Retry in a minute; nothing billed by the request itself.

Async render failures

render_error_code on a failed moment is one of:

Code	Agent action
`insufficient_credits`	Top up, then render again.
`source_expired`	Resubmit the video.
`render_interrupted`	Safe to POST the render again.
`render_failed`	Relay `render_error`; do not claim anything about billing.

Errors

The envelope

Error codes

Async render failures

On this page