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.| 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.
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.
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" }
]
}
}
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.
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.