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