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

# Errors

> Standard error envelope and common codes.

# Errors

Successful Cloud API responses use `{ "data": … }` or `{ "data": […], "meta": … }` — see [API reference](/api/introduction#response-shape). **Errors are not wrapped in `data`.**

Failed requests return JSON:

```json theme={"system"}
{
  "error": {
    "code": "bad_request",
    "message": "Human-readable explanation"
  }
}
```

Some validation errors include structured `details` (logged server-side; when returned, e.g. SICAR document preflight):

```json theme={"system"}
{
  "error": {
    "code": "bad_request",
    "message": "Document validation failed",
    "details": {
      "issues": [
        {
          "field": "lines[].art_id",
          "id": 999,
          "message": "art_id 999 not found or inactive in articulo"
        }
      ]
    }
  }
}
```

<Note>
  Depending on the error middleware path, `details` may be omitted from the HTTP body even when set on the server error. Prefer relying on `code` + `message`; treat `details` as best-effort when present.
</Note>

## Common codes

| HTTP | `code`           | Meaning                                                                                                                                                                           |
| ---- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`    | Validation / bad input                                                                                                                                                            |
| 401  | `unauthorized`   | Missing/invalid API key                                                                                                                                                           |
| 403  | `forbidden`      | Insufficient permissions                                                                                                                                                          |
| 404  | `not_found`      | Resource missing (or hidden for enumeration)                                                                                                                                      |
| 409  | `conflict`       | State conflict (e.g. delete customer with active licenses/devices; **revoke license** while `pending`/`enrolled` devices remain — see `details.device_id` / `details.device_ids`) |
| 429  | `rate_limited`   | Too many requests — see [Rate limits](/api/rate-limits)                                                                                                                           |
| 500  | `internal_error` | Unexpected failure                                                                                                                                                                |

## Device / Gateway failures

Function invoke may return HTTP 200 with an agent error inside `data.result`:

```json theme={"system"}
{
  "data": {
    "device_id": "…",
    "function_id": "sicarv4.products.search",
    "operation": "db.query",
    "result": {
      "status": "error",
      "error": { "code": "…", "message": "…" }
    }
  }
}
```

Always check `data.result.status` / `data.result.error` for device-side failures (offline, SQL error, timeout).