Error reference¶

One envelope, one code table, every surface

Every REST error is the same JSON shape, every gRPC error maps onto the same taxonomy, and every SDK turns both into the same typed exception hierarchy. This page is the single table to check when a call fails.

The envelope¶

Every non-2xx REST response is:

{
  "code": "QUERY_INVALID",
  "message": "human-readable description",
  "request_id": "0197c1a2-...-..."
}

• code is a stable, machine-checkable string (&'static str in the server).
• message is human-readable; for validation failures it carries a JSON pointer to the offending field (e.g. /where/severity: expected an operator object like {"$eq": ...}).
• request_id correlates with server logs; it is echoed from the request-id middleware and is the same UUID as the x-request-id response header. It is omitted only in the rare case no request id was available.

Every response, error or not, carries the x-request-id header, minted fresh (UUIDv7) by the outermost middleware layer for every request.

Error codes¶

Where each surface raises them¶

Full per-endpoint status/code tables are in REST API.

Validation errors carry a JSON pointer¶

QUERY_INVALID and COMPARE_INVALID messages are not free text, they name the exact field:

{
  "code": "QUERY_INVALID",
  "message": "/where/severity: expected an operator object like {\"$eq\": ...}",
  "request_id": "..."
}

This is the same pointer format the query language fixture corpus pins, and the same format MCP tools echo back for their findRecords/generate/compareSnapshots validation failures (as a tool-level {"error": "query_invalid", "message": "..."}, not a transport-level error, see MCP tools).

gRPC status mapping¶

gRPC has no envelope; it maps the same taxonomy onto standard Status codes (grpc-contracts spec §6):

See gRPC API › Error mapping for how this plays out per-RPC.

How the SDKs surface errors¶

Both SDKs parse the envelope into a typed exception hierarchy rooted at a common base carrying {code, status, requestId} (or request_id in Python):

The TypeScript SDK additionally maps gRPC status codes onto this same hierarchy via fromGrpcError: UNAUTHENTICATED → AuthError, INVALID_ARGUMENT → QueryInvalidError/ValidationError, NOT_FOUND/ALREADY_EXISTS/ABORTED → NotFoundError/ConflictError, UNIMPLEMENTED → UnimplementedError, DEADLINE_EXCEEDED/UNAVAILABLE → ServerError.

See TypeScript SDK › Errors and Python SDK › Errors for the exact class shapes and retry semantics (only idempotent calls retry, and only on 5xx/transport failures, never on any 4xx, including all of the codes above).

Related¶

• REST API - per-endpoint status/code tables
• gRPC API - RPC-level error mapping and auth failure modes
• Query language - the grammar behind every QUERY_INVALID
• MCP tools - tool-level error shapes for the agent surface
• TypeScript SDK / Python SDK - typed exception hierarchies and retry policy