Errors and recovery

All V1 errors use a single envelope:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits to start this job",
    "request_id": "req_123abc"
  }
}

Use code for program logic. request_id correlates the response with Viggle logs and support systems; internal implementation codes are not exposed.

HTTP	`error.code`	What to do
400	`invalid_request`	Correct the request or resource ID.
401	`authentication_required`, `invalid_api_key`	Add or replace the API key.
402	`insufficient_credits`	Add credits in the Dashboard.
404	`not_found`	Verify the ID and that it belongs to the current account.
409	`id_already_exists`	Use a new client task ID where applicable.
5xx	`service_unavailable`, `internal_error`, `unexpected_error`	Retry with backoff; contact support if persistent.

Common V1 error codes

Code	Typical cause	Recovery
`invalid_request`	Missing input, malformed field, unsupported parameter combination, or resource ID with the wrong prefix.	Correct the request from the endpoint’s parameter table.
`motion_not_ready`	A reusable Motion is still processing.	Poll the Motion until `ready`, then submit the Render.
`task_failed`	An asynchronous job ended unsuccessfully.	Treat as terminal; inspect the internal code and retry only when appropriate.
`worker_stopped` / `service_unavailable`	Temporary processing capacity issue.	Retry with exponential backoff.

Retry policy

Retry only temporary service failures. Start with a short delay and increase it between attempts; do not retry 400-, 401-, 402-, 404-, or 409-level responses unchanged. Because V1 does not expose idempotency keys, do not automatically retry a create request after a network timeout unless your integration can safely determine that no resource was created.

Failed async jobs

An HTTP 200 response from a status endpoint can still describe a failed job:

{
  "id": "render_123abc",
  "status": "failed",
  "error": {
    "code": "task_failed",
    "message": "The render could not be completed.",
    "request_id": "req_123abc"
  }
}

Treat failed as terminal. Keep the resource ID and X-Request-Id for support.

Get Started

Guides

Production

Common V1 error codes

Retry policy

Failed async jobs

​Common V1 error codes

​Retry policy

​Failed async jobs

Common V1 error codes

Retry policy

Failed async jobs