Errors

All errors return JSON with a structured detail field containing an error code:

{
  "detail": {
    "error_code": "CS-UORC01-002",
    "error": "invalid_request",
    "message": "Request failed validation"
  }
}

When contacting support, always include the error_code from the response. Email [email protected] with the error code and your job ID for fastest resolution.

Error response fields

Field	Description
`error_code`	Unique identifier (e.g. `CS-UORC01-002`). Always include this when contacting support.
`message`	Human-readable description of what went wrong
`action`	What you can do to fix it

Error codes by category

Authentication (401)

Code	Message	Action
`CS-UORC01-006`	Authentication required	Include `Authorization: Bearer sk-...` header
`CS-UORC01-007`	Invalid or expired API key	Check your API key is correct or generate a new one

Credits (402)

Code	Message	Action
`CS-UORC01-008`	Insufficient credits to start this job	Top up your credits in the dashboard

Input validation (400)

Code	Message	Action
`CS-UORC01-002`	Request failed validation	Check your request parameters match the API spec
`CS-ORIV-001`	Reference image is required	Upload a `ref_image` (PNG/JPG)
`CS-ORIV-002`	Driving video is required	Upload a `driving_video` (MP4)
`CS-ORIV-003`	Video format not supported	Upload MP4, MOV, or AVI format
`CS-ORIV-004`	Video exceeds maximum duration	Keep video under 10 minutes
`CS-ORIV-005`	Video file too large	Keep file under 500MB
`CS-ORIV-006`	Video resolution too high	Keep resolution under 4096x4096
`CS-ORIV-007`	Could not read video file	Ensure the file is a valid video
`CS-ORIV-008`	Character not found	Check the `character_id` exists
`CS-ORIV-009`	Scene not found	Check the `scene_id` exists
`CS-ORIV-010`	Scene preprocessing not complete	Wait for scene status to be `ready` before rendering
`CS-ORIV-011`	Invalid background mode	Use `original`, `solid`, or `transparent` (`inpaint` is accepted as alias for `original`)

| CS-ORVV-004 | Video dimensions must be even | Re-encode with even width/height (e.g. 1920x1080) |

Job status (404 / 410)

Code	Message	Action
`CS-UORC01-003`	Resource not found	Check the job or task ID is correct
`CS-ORJC-003`	Result has expired	Submit a new job — results expire after 1 hour
`CS-UORC01-004`	Internal server error	Retry the job. If persistent, contact support with the error code.

Conflict (409)

Code	Message	Action
`CS-UORC01-015`	A task with this id already exists	Use a new `task_id` (Extract idempotency)

Extract task failures (200 body / 502)

These apply to the Extract API.

Code	Message	Action
`CS-UORC01-016`	Extract service temporarily unavailable	Retry in a few seconds (HTTP 502)
`CS-UORC01-017`	Extract task failed	`GET /api/extract/{task_id}` returns HTTP 200 with `status=failed`. Retry the task; if persistent, contact support with the error code.

Processing errors (500)

Code	Message	Action
`CS-UORC01-009`	Worker stopped responding before the job completed	Retry the job
`CS-UORC01-013`	Scene model mismatch — scene was preprocessed on a different model than requested	Create a new scene with the correct `model` parameter, or render without specifying `model`
`CS-UWRK02-001`	GPU memory pressure detected — job stopped safely before it could crash	Retry the job. If it recurs, try a lower resolution or shorter video
`CS-UWRK02-002`	GPU ran out of memory (OOM) while processing	Retry with a lower resolution or shorter video. If persistent, contact support
`CS-ENEC-001`	Could not access the video	Retry the job
`CS-ENEC-004`	No humans detected in some frames	Ensure the person is visible throughout the video
`CS-RNRD-003`	Processing resources exceeded	Try a lower resolution video
`CS-MGMR-001`	Some video segments are missing	Retry the job

Out-of-memory failures now consistently report CS-UWRK02-002. If you track failures by error_code, expect OOM jobs to move under this code going forward. CS-UWRK02-001 is new — it’s a proactive check that can end a job slightly earlier than before under heavy GPU memory pressure, in exchange for a clean failure instead of an unpredictable crash.

Capacity (503)

Code	Message	Action
`CS-ORRS-001`	All workers are busy	Retry in a few seconds

Catch-all (500)

Code	Message	Action
`CS-UORC99-999`	Unexpected server error	Retry the job. If persistent, contact support with this error code.

HTTP status codes

Status	Meaning	Error codes
400	Bad Request	`CS-UORC01-002`, `CS-ORIV-*`
401	Unauthorized	`CS-UORC01-006`, `CS-UORC01-007`
402	Payment Required	`CS-UORC01-008`
404	Not Found	`CS-UORC01-003`
409	Conflict	`CS-UORC01-015`
410	Gone	`CS-ORJC-003`
500	Server Error	`CS-UORC01-004`, `CS-UORC01-009`, `CS-UORC99-999`, `CS-UWRK02-`, `CS-ENEC-`, `CS-RNRD-`, `CS-MGMR-`
502	Bad Gateway	`CS-UORC01-016`
503	Unavailable	`CS-ORRS-*`

Error handling

Implement retry logic

For transient errors (500, 503), use exponential backoff:

import time, requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code in (500, 503):
            time.sleep(2 ** attempt)
            continue
        return response
    raise Exception("Max retries exceeded")

Handle error codes

Check for error codes in the response:

response = requests.post(url, headers=headers, files=files)
if response.status_code != 200:
    error = response.json().get("detail", {})
    code = error.get("error_code", "unknown")
    message = error.get("message", response.text)
    category = error.get("error", "")
    print(f"Error {code} ({category}): {message}")
    # Forward to support: [email protected] with the error_code

Handle processing failures

Always check for failed status and error codes when polling:

while True:
    status = get_status(job_id)
    if status["status"] == "complete":
        break
    elif status["status"] == "failed":
        code = status.get("error_code", "unknown")
        print(f"Job failed: {code} - {status.get('error_message')}")
        print("Forward this error code to [email protected]")
        break
    time.sleep(3)

Validate before rendering

Check that assets are ready before creating render jobs:

character = get_character(character_id)
scene = get_scene(scene_id)
if character["status"] != "ready":
    raise Exception("Character not ready -- wait for status 'ready'")
if scene["status"] != "ready":
    raise Exception("Scene not ready -- wait for status 'ready'")
create_render_job(character_id, scene_id)

Need help?

If you encounter an error that persists after retrying, email [email protected] with:

The error_code from the response
Your job ID
The request you made (endpoint, parameters)

This helps us resolve your issue quickly.

Get Started

Guides

Advanced

Reference

Error response fields

Error codes by category

Authentication (401)

Credits (402)

Input validation (400)

Job status (404 / 410)

Conflict (409)

Extract task failures (200 body / 502)

Processing errors (500)

Capacity (503)

Catch-all (500)

HTTP status codes

Error handling

Need help?

​Error response fields

​Error codes by category

​Authentication (401)

​Credits (402)

​Input validation (400)

​Job status (404 / 410)

​Conflict (409)

​Extract task failures (200 body / 502)

​Processing errors (500)

​Capacity (503)

​Catch-all (500)

​HTTP status codes

​Error handling

​Need help?

Error response fields

Error codes by category

Authentication (401)

Credits (402)

Input validation (400)

Job status (404 / 410)

Conflict (409)

Extract task failures (200 body / 502)

Processing errors (500)

Capacity (503)

Catch-all (500)

HTTP status codes

Error handling

Need help?