Errors

Every endpoint returns a predictable error envelope:

json
{ "error": "Project not found" }

Some endpoints add a detail field with extra context:

json
{  "error": "Brand detection failed",  "detail": "Firecrawl returned 503"}

HTTP status conventions

Validation errors

When a Zod schema rejects a request body or path/query param, the server returns 400 with a structured details field:

json
{  "error": "Validation failed",  "details": {    "fieldErrors": {      "email": ["Invalid email"],      "password": ["Password must be at least 8 characters"]    },    "formErrors": []  }}

Use details.fieldErrors for per-field UI feedback.

Asset failure surface

Asset failures are richer than HTTP errors — they have stable error_code strings:

json
{  "error": "last generation failed",  "asset_id": "a25b…",  "hint": "POST /api/v1/regenerate/{asset_id}"}

For full lifecycle context, fetch the asset:

bash
curl https://motioness.com/api/assets/$ASSET_ID -b cookie.txt# → { "asset": { ..., "error": "vision_blocked: NSFW source", "status": "failed" }, ... }

The full enum of error_code values is in the event types reference.

Quota errors

json
{  "error": "monthly limit reached",  "upgrade_url": "https://motioness.com/pricing"}

json
{ "error": "overage disabled — enable in project settings or upgrade plan" }

Rate-limit errors

json
{ "error": "rate limited", "retry_after_ms": 5000 }

Headers also carry Retry-After (seconds, rounded). Back off and retry.

When to contact support

Quote the X-Request-Id from the response. With it we can pull:

• The full event log for the request
• All Replicate predictions tied to the asset
• The exact prompt the vision model wrote
• Webhook delivery attempts

Email: hi@motioness.com.