Skip to main content
All errors return JSON with a structured detail field containing an error code: 
{
  "detail": {
    "error_code": "CS-UORC01-002",
    "message": "Request failed validation",
    "action": "Check your request parameters"
  }
}
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

FieldDescription
error_codeUnique identifier (e.g. CS-UORC01-002). Always include this when contacting support.
messageHuman-readable description of what went wrong
actionWhat you can do to fix it

​
Error codes by category

​
Authentication (401)

CodeMessageAction
CS-UORC01-006Authentication requiredInclude Authorization: Bearer sk-... header
CS-UORC01-007Invalid or expired API keyCheck your API key is correct or generate a new one

​
Credits (402)

CodeMessageAction
CS-UORC01-008Insufficient credits to start this jobTop up your credits in the dashboard

​
Input validation (400)

CodeMessageAction
CS-UORC01-001Fast mode is temporarily unavailableRetry without fast=true
CS-UORC01-002Request failed validationCheck your request parameters match the API spec
CS-ORIV-001Reference image is requiredUpload a ref_image (PNG/JPG)
CS-ORIV-002Driving video is requiredUpload a driving_video (MP4)
CS-ORIV-003Video format not supportedUpload MP4, MOV, or AVI format
CS-ORIV-004Video exceeds maximum durationKeep video under 5 minutes
CS-ORIV-005Video file too largeKeep file under 500MB
CS-ORIV-006Video resolution too highKeep resolution under 4096x4096
CS-ORIV-007Could not read video fileEnsure the file is a valid video
CS-ORIV-008Character not foundCheck the character_id exists
CS-ORIV-009Scene not foundCheck the scene_id exists
CS-ORIV-010Scene preprocessing not completeWait for scene status to be ready before rendering
CS-ORIV-011Invalid background modeUse original, solid, or transparent
CS-ORIV-012Invalid character_mapping JSONProvide valid JSON for multi-character mapping

​
Job status (404 / 410)

CodeMessageAction
CS-UORC01-003Resource not foundCheck the job ID is correct
CS-ORJC-003Result has expiredSubmit a new job — results expire after 24 hours
CS-UORC01-004Internal server errorRetry the job. If persistent, contact support with the error code.

​
Processing errors (500)

CodeMessageAction
CS-UORC01-009Worker stopped responding before the job completedRetry the job
CS-UORC01-010Fast mode sub-job failedRetry the job, or use normal mode instead of fast mode
CS-UORC01-011Fast mode merge failedRetry the job
CS-ENEC-001Could not access the videoRetry the job
CS-ENEC-004No humans detected in some framesEnsure the person is visible throughout the video
CS-RNRD-003Processing resources exceededTry a lower resolution video
CS-MGMR-001Some video segments are missingRetry the job

​
Capacity (503)

CodeMessageAction
CS-ORRS-001All workers are busyRetry in a few seconds or use normal mode instead of fast mode

​
Catch-all (500)

CodeMessageAction
CS-UORC99-999Unexpected server errorRetry the job. If persistent, contact support with this error code.

​
HTTP status codes

StatusMeaningError codes
400Bad RequestCS-UORC01-001, CS-UORC01-002, CS-ORIV-*
401UnauthorizedCS-UORC01-006, CS-UORC01-007
402Payment RequiredCS-UORC01-008
404Not FoundCS-UORC01-003
410GoneCS-ORJC-003
500Server ErrorCS-UORC01-004, CS-UORC01-009 — 011, CS-UORC99-999, CS-ENEC-*, CS-RNRD-*, CS-MGMR-*
503UnavailableCS-ORRS-*

​
Error handling

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")
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)
    action = error.get("action", "")
    print(f"Error {code}: {message}")
    print(f"Fix: {action}")
    # Forward to support: [email protected] with the error_code
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)
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:
  1. The error_code from the response
  2. Your job ID
  3. The request you made (endpoint, parameters)
This helps us resolve your issue quickly.