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

# Errors

Error envelope shape and the canonical status codes.

# 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

| Status | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `202` | Generation in flight (proxy URL only) |
| `400` | Validation error |
| `401` | Authentication required |
| `403` | Forbidden (wrong project key, origin not allowed, signature invalid) |
| `404` | Resource not found / not owned |
| `413` | Payload too large |
| `415` | Unsupported media type |
| `429` | Rate limited or quota exceeded |
| `500` | Server error (cf. `X-Request-Id` for support) |
| `502` | Upstream error (Replicate/Firecrawl/etc) |

## 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](/reference/event-types#error_code-enum).

## 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](mailto:hi@motioness.com).