> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> API error codes and handling
All errors return JSON with a structured `detail` field containing an error code:
```json theme={null}
{
"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 **[support@viggle.ai](mailto:support@viggle.ai)** 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](https://portal.viggle.ai/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](/api-reference/extract/static-bin).
| 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
For transient errors (500, 503), use exponential backoff:
```python theme={null}
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:
```python theme={null}
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: support@viggle.ai with the error_code
```
Always check for failed status and error codes when polling:
```python theme={null}
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 support@viggle.ai")
break
time.sleep(3)
```
Check that assets are ready before creating render jobs:
```python theme={null}
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 **[support@viggle.ai](mailto:support@viggle.ai)** 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.