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

# Errors

> Attack Surface Query error codes, HTTP statuses, validation issues and how to fix them

## Error shape

An error is an object with a `code`, a readable `message`, and details depending on the code:

```json theme={null}
{
  "error": {
    "code": "INVALID_QUERY",
    "message": "2 issue(s) in the query",
    "issues": [
      { "path": "queries.ports.where.items[0].value", "code": "INVALID_VALUE",
        "message": "\"https\" is not a valid port" },
      { "path": "queries.ports.select[1]", "code": "UNKNOWN_FIELD",
        "message": "services has no field \"hostname\". (fields of services: id, value, port, isErrorPage, firstSeen, lastSeen, isNew; related rows: host.<field>, target.<field>, http.<field>; lists (include or where only): technologies, tls, statusCodes, urls, tags)" }
    ]
  }
}
```

Messages never contain SQL or database internals.

## Where errors appear

* **The whole batch is refused** — with the HTTP status below and the body `{ "error": { … } }` — when it is invalid, refers to a resource you cannot read, or is over budget. Nothing runs: all validation and costing happen before the database is touched.
* **One query fails at run time** (it times out, for example): the batch still returns HTTP 200, the other queries return their rows, and the failed one carries `{ "error": { "code", "message" } }` under its name in `data`.
* **AI agent and MCP**: errors are returned as the tool result, `{ "error": { … } }`, so the assistant can read them and retry.

## Error codes

| Code | HTTP | Meaning | What to do |
| - | :-: | - | - |
| `INVALID_QUERY` | 400 | The batch has one or more problems, listed in `issues` | Fix every issue (see below) and send again |
| `INVALID_CURSOR` | 400 | The cursor is malformed, or belongs to another query or workspace | Send the query again without `cursor`; keep the filter and order unchanged while paging |
| `PERMISSION_DENIED` | 403 | The batch reads a resource you lack the permission for | Remove that resource, field or filter, or ask for the permission (see [Permissions](https://docs.oasm.io/attack-surface-query/overview.md#permissions)) |
| `NOT_FOUND` | 404 | No such saved query or report job in this workspace (report results expire after one hour) | Check the id; queue the report again |
| `COST_EXCEEDED` | 422 | The query is estimated to be too expensive: `cost`, `budget`, and `hints` (or `estimatedRows` from the planner) | Follow the hints: add a window or exact filter, lower `limit` or include limits, drop `withTotal` — or use report mode |
| `BUSY` | 503 | Too many queries are running, or the database is busy | Retry after a short pause |
| `QUERY_TIMEOUT` | 504 | A statement or the batch ran out of time | Narrow the query (window, exact filter, smaller page), or use report mode |
| `INTERNAL` | 500 | Unexpected failure, logged on the server | Retry; report it if it persists |

A `COST_EXCEEDED` error — here 200 hosts with up to 20 services each — looks like:

```json theme={null}
{
  "error": {
    "code": "COST_EXCEEDED",
    "message": "Query \"hosts\" is too broad (cost 2760, budget 1000)",
    "cost": 2760,
    "budget": 1000,
    "hints": [
      "each include fetches up to its own limit per row: keep limit × include limit small (e.g. limit 50 with include limit 5), or query the child resource directly with a filter",
      "add a window (e.g. \"window\": { \"since\": \"now-7d\" })",
      "lower limit"
    ]
  }
}
```

Interactive queries are also checked by the database planner. When it expects the query to scan too much data, `cost` and `budget` are the planner's numbers (*"would scan too much data"*); when it expects to sort too many rows on a field without an index, the error carries `estimatedRows` instead.

## Validation issues

Each issue of an `INVALID_QUERY` error has a `path` into your input, down to the faulty part of a nested filter (`queries.<name>.where.items[1].not.items[0].op`), a `code` and a `message`. Messages for unknown or unusable names list the valid ones: an operator a field does not take lists the operators it does.

| Issue code | Cause | Example |
| - | - | - |
| `INVALID_SHAPE` | Wrong structure or type, a missing required key, or an unknown key | `"selct"`, `"limit": "50"`, a query name starting with a digit, an empty group, `every` without `where`, a `$param` the saved query does not declare |
| `UNKNOWN_RESOURCE` | `from` is not a resource | `"from": "assets"` |
| `UNKNOWN_FIELD` | No such field on the resource or relation, or a `having` field that is neither a group key nor an aggregate | `"hostname"` on `services` (use `host.value`) |
| `UNKNOWN_RELATION` | No such relation, a list used where a single row is needed, or a list inside a relation test | `include: { "certificates": … }`; a list in `select`; `"relation": "host"` (a single row, not a list) |
| `OP_NOT_ALLOWED` | The operator does not apply to the field's type | `contains` on `port`; `eq` on `firstSeen`; `isNull` on a field that is never empty |
| `INVALID_VALUE` | The value does not fit the field or the operator | `"abc"` for a port, `"urgent"` for a severity, an array for `eq`, `between` with one value or in the wrong order, an unknown `options.timezone` |
| `INVALID_TIME` | A time expression is malformed or out of range | `"7 days ago"`, a time without offset, `now+1d` in a window |
| `MODE_CONFLICT` | Parts of the query cannot be combined | `groupBy`, `having` or `fill` without `aggregate`; `select` or `cursor` with `aggregate`; `fill` without a window; `quantifier` and `count` in one relation test; report mode from the agent |
| `LIMIT_EXCEEDED` | A [limit](https://docs.oasm.io/attack-surface-query/paging-and-limits.md#limits) is exceeded | `"limit": 5000` interactively; a sixth include; a fifth level of filter groups; a filled series with more buckets than the row limit |
| `NOT_SORTABLE` | The field cannot be used in `orderBy` | `orderBy` on `name` of `vulnerabilities` |
| `NOT_GROUPABLE` | The field cannot be a group key | `groupBy: ["url"]`; a time field without a bucket |
| `HEAVY_FIELD_NOT_ALLOWED` | A large HTTP field requested by the AI agent or MCP | `http.body`, `http.rawHeader` |

> [!TIP]
>
> Use `POST /api/attack-surface/explain` to check a batch: it reports the same validation issues and the cost of every query without running anything.


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