MuviaDevelopers
Guides: Errors

Errors

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

{
  "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.
403 forbidden The key is valid but does not hold the endpoint's scope. No — see 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.
500 internal_error An unexpected server error. Yes, with backoff.
501 not_implemented The operation is not available. No — see the OpenAPI document.
503 service_unavailable The data store behind dataset rows did not answer. Yes, with backoff.

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

Unknown paths

A path that is not an operation answers 404:

{
  "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 on this site.

Validation errors

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

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