> ## 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 and recovery

> Handle V1 errors predictably.

All V1 errors use a single envelope:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.