Errors

Every error from a served route uses the same envelope as the TypeScript Serve runtime:

{
  "error": {
    "type": "UNAUTHORIZED",
    "message": "Access denied",
    "details": { "reason": "missing_credentials" }
  }
}

Error responses are sent with Cache-Control: no-store and an x-request-id.

Error types

Status	`type`	When
400	`VALIDATION_ERROR`	Invalid body, unknown fields, or an unknown dimension or measure
401	`UNAUTHORIZED`	Missing or rejected credentials
403	`FORBIDDEN`	Missing role or scope, or a tenant policy mismatch
404	`NOT_FOUND`	Unknown path or method
413	`PAYLOAD_TOO_LARGE`	Body or result over its byte limit
429	`RATE_LIMITED`	Rate limit exhausted
503	`SERVICE_UNAVAILABLE`	Authentication down, the server at capacity, or ClickHouse rejecting the server's own credentials or permissions (the reason goes to the server log with the request id)
504	`GATEWAY_TIMEOUT`	Request or query deadline missed
500	`INTERNAL_SERVER_ERROR`	Unexpected failure

Validation errors are 400 with details.issues[].path, as in TypeScript. Submitted values are never echoed back. Endpoints with a strict client profile (client_profile=) answer any invalid query with the fixed message Invalid client query. and no details. They also answer 409 with details.code CLIENT_SCHEMA_CHANGED when the caller's schema pin is stale.

Raising errors from your routes

from hypequery.serve import Call, ServeError, ServeResponse


async def report(call: Call) -> ServeResponse:
    raise ServeError(404, "NOT_FOUND", "Report not found")

ServeError(status, type, message, *, details=None, headers=None) is sent as written, like TypeScript's ServeHttpError.
A dataset query error maps its category to a status and type, for example a missed deadline becomes 504 GATEWAY_TIMEOUT.
Anything else is logged to the hypequery.serve logger with its request id and answered with a fixed 500. The failure's own text never reaches the response body.

Error types

Raising errors from your routes

On this page

Get early access to hypequery cloud.