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. 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:

{
  "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.

{
  "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

{
  "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.

{"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:

{"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 for request examples and run states.

Getting Started

Working in Motion

Team administration

AI Agents

Guides

Common errors

400 Invalid request

401 Authentication required

402 Insufficient credits

404 Job not found

409 Followup requires completed job

500 Internal server error

Validation error example

403 Engine access required

Engine and template errors

Automation errors

​Common errors

​400 Invalid request

​401 Authentication required

​402 Insufficient credits

​404 Job not found

​409 Followup requires completed job

​500 Internal server error

​Validation error example

​403 Engine access required

​Engine and template errors

​Automation errors

Common errors

400 Invalid request

401 Authentication required

402 Insufficient credits

404 Job not found

409 Followup requires completed job

500 Internal server error

Validation error example

403 Engine access required

Engine and template errors

Automation errors