Skip to main content

Error shape

An error is an object with a code, a readable message, and details depending on the code:
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

A COST_EXCEEDED error — here 200 hosts with up to 20 services each — looks like:
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.
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.