> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

The Motion API returns JSON errors.

## Common errors

### 400 Invalid request

The request body failed validation.

Examples:

* Missing `prompt`.
* More than 100 attachments.
* Invalid attachment URL.
* Non-YouTube `style_reference_url`.

### 401 Authentication required

The request did not include a valid API key or OAuth access token for this resource.

### 402 Insufficient credits

A credit-paused job cannot resume until the API key owner adds enough credits.

Purchase credits and configure auto top-ups in the Motion web app at [motion.so](https://motion.so). Flex packs and standard manual top-ups cost \$6 per 200 credits (3¢ per credit). Credit purchasing and auto top-up settings are not available through the API.

Example:

```json theme={null}
{
  "error": "insufficient_credits",
  "message": "Add credits before resuming this job.",
  "status": "awaiting_user_input"
}
```

### 404 Job not found

The job does not exist or is not owned by the API key user.

### 409 Followup requires completed job

Followups can only be created for jobs that are `completed` or `awaiting_user_input`.

```json theme={null}
{
  "error": "followup_requires_completed_job",
  "message": "Followups can only be created for Motion jobs that are completed or waiting on user input.",
  "status": "running"
}
```

### 500 Internal server error

The job could not be created or read due to an internal service error.

## Validation error example

```json theme={null}
{
  "error": "Invalid request",
  "details": [
    {
      "code": "too_big",
      "maximum": 100,
      "type": "array",
      "inclusive": true,
      "message": "Array must contain at most 100 element(s)",
      "path": ["attachments"]
    }
  ]
}
```

### 403 Engine access required

An explicit engine choice is not available to your account. Read `GET /engines` or MCP `list_engines` to see your available engines. API keys, OAuth authorization, and credits do not grant engine access.

```json theme={null}
{"error":"engine_access_required", "message":"Your account does not have access to this engine. Use list_engines or GET /engines to see available engines."}
```

## Engine and template errors

Invalid inputs return HTTP 400. Engine access errors return HTTP 403. MCP reports these failures as tool errors; read the returned code and message. Plan errors such as `motion_pro_feature_required` can be returned when applying paid features; omit the feature or use an eligible plan.

| Code | Resolution |
| - | - |
| `invalid_engine` | Choose an engine returned by `list_engines` or `GET /engines`. |
| `invalid_effort` | Choose an effort supported by your selected engine: `light`, `medium`, or `high` for Motion; `standard` or `extended` for GVA. |
| `conflicting_effort` | Send `effort` alone, or make the deprecated `mode` alias match. |
| `engine_locked` | Create a new job to use another engine. |
| `template_locked` | Create a new job to select another template. |
| `invalid_template` | Use an identifier returned by `list_templates`. |
| `template_unavailable` | Choose a published template available to your account for the selected engine. |
| `motion_pro_feature_required` | Use Pro or Max to apply a template, or omit the paid feature. |
| `templates_unsupported` | The selected engine does not support templates; omit `template` or choose another engine. |

## Automation errors

Automation errors contain a readable `message` and a stable `error` code:

```json theme={null}
{"error":"update_conflict","message":"Automation execution settings changed. Read the automation again before retrying this edit."}
```

| Status and code | Resolution |
| - | - |
| `400 invalid_input` or `invalid_cursor` | Correct the named field; reuse only the opaque cursor returned by that endpoint. |
| `400 unavailable_trigger` | Choose a trigger returned by automation capabilities. |
| `401 invalid_token` or `unauthorized` | Authenticate again. REST requires the full MCP audience, not a restricted profile token. |
| `403 insufficient_scope` | Reauthorize with `motion:automations:read` or `motion:automations:write` as required. |
| `403 access_denied` | Automation access must be enabled for this account. |
| `403 restricted_automation` or `restricted_engine` | Use Motion to manage an automation outside the connected profile’s authoring or engine limits. |
| `404 unavailable` | The environment does not expose automations. |
| `404 not_found` | The automation or run does not exist or belongs to another account. |
| `409 automation_paused` | Resume the automation before running or retrying it. |
| `409 update_conflict` | Read the latest execution settings before retrying the edit. |
| `503 temporarily_unavailable` | Retry later. |

Only schedule automations support manual invocations. Channel runs need a real event. Only failed or blocked attempts can be retried. Read [Automations](https://docs.motion.so/guides/automations.md) for request examples and run states.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.