# Errors

Every non-2xx response of the public API has the same envelope:

```json
{
  "error": {
    "code": "not_found",
    "message": "Project not found",
    "status": 404,
    "hint": "List the parent collection first and use an id it returns; ids of other companies answer the same."
  }
}
```

- `code` — a stable, machine-readable identifier. Branch on it, never on the
  message text.
- `message` — a human-readable English description. It may change.
- `status` — the HTTP status, repeated for convenience.
- `hint` — optional, one fixed sentence that says what to do next. It never
  quotes your request and never names anything beneath Muvia. Agents can show it
  as it is.
- `details` — optional structured context, such as the fields that failed
  validation.

## Error codes

| Status | Code | When | Retry? |
| --- | --- | --- | --- |
| 400 | `bad_request` | The request cannot be served as sent. | No — fix the request. |
| 401 | `unauthorized` | Missing, malformed, unknown, revoked or expired API key. Always the same response. | No — see [Authentication](/guides/authentication). |
| 403 | `forbidden` | The key is valid but does not hold the endpoint's scope. | No — see [Scopes](/guides/scopes). |
| 403 | `module_not_active` | The company has not activated the data export module. | No — a company administrator activates it. |
| 404 | `not_found` | No such resource in your company, including one that belongs to another company. | No. |
| 405 | `method_not_allowed` | The path exists but not for this method. The API is read-only: use `GET`. | No — use `GET`. |
| 409 | `conflict` | The project has no database, so its datasets have no rows to read; or the item changed meanwhile. | No — until the project gets one, or read the item again. |
| 422 | `validation_error` | A parameter failed validation; `details` names each one. | No — fix the request. |
| 422 | `query_failed` | The dataset's own query does not run: the dataset is broken, not your request. The query is never echoed back; other datasets are unaffected. | No — a person mends the dataset's query in Muvia. |
| 429 | `rate_limit_exceeded` | A rate-limit window is exhausted. | After `Retry-After` — see [Rate limits](/guides/rate-limits). |
| 500 | `internal_error` | An unexpected server error. | Yes, with backoff. |
| 501 | `not_implemented` | The operation is not available. | No — see the [OpenAPI document](/openapi.json). |
| 503 | `service_unavailable` | The data store behind dataset rows did not answer. | Yes, with backoff. |

New codes may appear within v1 (see [Versioning](/guides/versioning)). Handle
a code you do not know by its HTTP status.

## Unknown paths

A path that is not an operation answers `404`:

```json
{
  "error": {
    "code": "not_found",
    "message": "No such endpoint",
    "status": 404,
    "hint": "This path is not an operation of the API; the OpenAPI document lists every one, at openapi.json beside the v1 prefix."
  }
}
```

The OpenAPI document is at `/api/public/openapi.json` on the API host, and at
[/openapi.json](/openapi.json) on this site.

## Validation errors

A `422 validation_error` carries one entry per offending parameter, named by
`field`:

```json
{
  "error": {
    "code": "validation_error",
    "message": "The request is not valid",
    "status": 422,
    "details": [
      { "field": "size", "message": "Input should be less than or equal to 100" }
    ]
  }
}
```

## 404, not 403, for another company's data

Asking for a project, dataset or node that belongs to another company answers
`404`, the same as asking for one that does not exist. The API never confirms
that data outside your company exists.

## Backing off

For `500` and `503`, retry with exponential backoff and jitter — for example
1, 2, 4, 8 seconds, then give up and alert. For `429`, wait exactly as long as
`Retry-After` says. Never retry a `400`, `401`, `403`, `404` or `422` unchanged:
the answer will be the same.
