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

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# API errors

> Every failed Devias API call returns the same JSON shape with a status code and an error object holding a stable code, a message and optional details. Lists all codes (VALIDATION, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, PLAN_MISMATCH, RATE_LIMITED and more) with their HTTP status.

When a call fails, the response has a status code and a body like this:

```json theme={"dark"}
{
  "error": {
    "code": "VALIDATION",
    "message": "Validation failed",
    "details": {
      "issues": [
        { "path": "email", "code": "invalid_format", "message": "Invalid email address" }
      ]
    }
  }
}
```

`code` is stable and can be matched in code. `message` is for people. `details` is present when there is more to say, such as which fields were wrong, and is omitted otherwise.

## Error codes

| Code | Status | Meaning |
| - | - | - |
| `VALIDATION` | 400 | The request is not valid. `details` says what. |
| `INVALID_CURSOR` | 400 | The page cursor is not one the server gave. |
| `UNAUTHORIZED` | 401 | The caller is not signed in, or the key is wrong or expired. |
| `FORBIDDEN` | 403 | The caller is signed in but not allowed to do this. |
| `NOT_FOUND` | 404 | There is nothing there, or the caller cannot see it. |
| `CONFLICT` | 409 | Someone changed it first, or it cannot be done in this state. |
| `UNIQUE_VIOLATION` | 409 | A value that must be unique already exists. |
| `PLAN_MISMATCH` | 409 | The workspace changed since the plan was made. |
| `DESTRUCTIVE_CHANGE` | 409 | The change deletes data and that was not allowed. |
| `MISSING_DEPENDENCY` | 422 | Something it needs is missing, such as a module that is not installed. |
| `RATE_LIMITED` | 429 | Too many requests. Wait and retry. |
| `INTERNAL` | 500 | Something went wrong on the server. |

The SDK adds one more code, `NETWORK`, when the server could not be reached at all.

## Related

* [SDK errors](https://docs.devias.io/reference/sdk/client.md#errors): how they look in TypeScript.
* [Authentication](https://docs.devias.io/reference/api/authentication.md): resolve 401 and 403.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.