Error catalog · Automotion

Every error the platform can produce comes from this single catalog. Each error carries a stable code, a human-readable message, an optional path (the exact JSON path of the offending field) and a docsUrl pointing at its page below.

error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Opacity must be between 0 and 1.",
    "path": "scenes[0].elements[1].opacity",
    "docsUrl": "https://automotion.dev/docs/errors/validation_error"
  },
  "requestId": "req_0123456789abcdef0123456789abcdef"
}

Document-validation failures additionally include an errors array with all findings (error is always errors[0]), so you can fix everything in one pass.

Code	HTTP	Summary
`AUTH_TOKEN_EXPIRED`	400	The verification or password-reset link has expired.
`AUTH_TOKEN_INVALID`	400	The verification or password-reset link is invalid or already used.
`BILLING_WEBHOOK_INVALID`	400	A billing webhook signature or body failed verification.
`ELEMENT_ID_DUPLICATE`	400	Two elements share the same id; element ids must be unique across the movie.
`EMAIL_ALREADY_EXISTS`	400	An account with this email address already exists.
`SCENE_EMPTY`	400	A scene has no elements.
`SCENE_ID_DUPLICATE`	400	Two scenes share the same id; scene ids must be unique within the movie.
`SCHEMA_INVALID`	400	The movie document is not a valid Automotion movie.
`UNSUPPORTED_SCHEMA_VERSION`	400	The "schema" version tag is missing or not supported.
`VALIDATION_ERROR`	400	A field in the movie document failed validation.
`VARIABLE_MISSING`	400	A referenced variable has no supplied value and no default.
`VARIABLE_TYPE_MISMATCH`	400	A supplied variable value does not match its declared type.
`VARIABLE_UNDECLARED`	400	A {{placeholder}} references a variable that is not declared in movie.variables.
`UNAUTHORIZED`	401	The request is missing a valid API key.
`INSUFFICIENT_CREDITS`	402	The credit balance cannot cover this render's estimated cost.
`FORBIDDEN`	403	The API key is valid but not allowed to perform this action.
`TOPUP_REQUIRES_SUBSCRIPTION`	403	Credit top-ups are available to active subscribers only.
`WEBHOOKS_NOT_ALLOWED`	403	webhook_url requires a paid plan with the webhooks perk.
`NOT_FOUND`	404	The requested resource does not exist.
`USER_NOT_FOUND`	404	The referenced user does not exist.
`IDEMPOTENCY_KEY_REUSED`	409	An Idempotency-Key was reused with a different request body.
`ASSET_FETCH_FAILED`	422	A referenced asset could not be downloaded.
`ASSET_NOT_FOUND`	422	A referenced asset URL returned 404 or does not exist.
`ASSET_UNSUPPORTED_TYPE`	422	A referenced asset has an unsupported content type.
`HTTP_FETCH_FAILED`	422	An outbound HTTP fetch of a supplied URL failed.
`URL_NOT_ALLOWED`	422	A supplied URL was rejected by the egress guard (scheme or address not allowed).
`CONCURRENCY_LIMIT`	429	Too many renders are running concurrently for the plan.
`RATE_LIMITED`	429	Too many API requests in the current window.
`INTERNAL`	500	An unexpected internal error occurred.
`METERING_FAILED`	500	Usage metering could not be recorded.
`RENDER_FAILED`	500	The render pipeline failed to produce an output video.
`BILLING_FAILED`	502	A billing-provider operation failed.
`CACHE_FAILED`	502	A cache (Redis) operation failed.
`EMAIL_SEND_FAILED`	502	A transactional email could not be sent.
`IMAGE_GEN_FAILED`	502	AI image generation failed for an image element.
`LLM_FAILED`	502	AI text generation failed.
`QUEUE_FAILED`	502	A render-queue operation failed.
`STORAGE_FAILED`	502	A storage (S3) operation failed.
`TTS_FAILED`	502	Text-to-speech synthesis failed for a voice element.
`LOCK_NOT_ACQUIRED`	503	A distributed lock could not be acquired; the operation is safe to retry.
`RENDER_TIMEOUT`	504	The render did not finish within the allowed time.