Endpoints troubleshooting

This page covers troubleshooting for Endpoints. For setup, see the installation guide.

Check the Logs tab

The Logs tab on each endpoint's page shows one entry per execution, including both successful and failed runs. Each entry includes metadata like the execution path (inline or materialized), cache outcome, duration, and row count.

Rejected requests that fail validation – such as an invalid refresh value or a missing limit for pagination – also appear as ERROR entries. Filter by log level or search by free text to find specific entries.

Successful runs return an execution_id in the API response. This matches the log entry's instance ID, so you can trace a specific API response back to its log. See execution logs for more details.

Endpoint not found (404)

Verify the endpoint name is correct
Check that the endpoint is active – inactive endpoints return 404
Ensure you're using the correct project ID

Authentication errors (401/403)

Verify your personal API key is correct
Check that your API key has the endpoint:read scope
Ensure you're including the Authorization: Bearer <key> header

Version not found

If you get "Version X not found for endpoint":

Check available versions in the endpoint's UI
Omit the version parameter to use the latest version

Variable errors

"Variable 'X' is not allowed for this endpoint"

Check the variables documentation for which variables are supported
SQL endpoints only accept variables explicitly defined in the query
Insight endpoints accept the breakdown property name and date_from/date_to (non-materialized only)

"Query references undefined variable(s): X, Y"

Your query uses {variables.X} placeholder(s) that don't have matching variable definitions
Define the variable in the data management variables page with a code_name matching the placeholder name
Ensure the variable is linked to your endpoint

"Variable ID(s) not valid UUIDs"

Variable IDs must be valid UUID format
Check that you're using the correct variable ID from data management variables

"Variable ID(s) not found"

The variable ID(s) don't exist in your project
Create the variable in data management variables
Verify you're using the correct project

Breaking change

The filters_override parameter has been removed. Requests using filters_override return a validation error. Use variables instead. See the variables documentation for migration guidance.

Rate limiting (429)

"Too many concurrent requests. Please try again later."

You've hit the concurrency limit
Reduce parallel requests or wait before retrying

Query performance errors (400)

The following query performance errors return HTTP 400 with a code field. Change the query before you retry these errors.

Code	Cause	Recommended action
`query_timeout`	The query exceeded the execution time limit	Narrow the date range or add filters to reduce the data scanned
`query_memory_limit`	The query exceeded the memory limit	Reduce the query scope or simplify aggregations
`query_too_large`	The query text is too large to execute	Reduce the size of the query text
`query_estimated_too_slow`	The estimated execution time exceeds the limit	Narrow the time range or reduce the data scanned

For repeated timeout, memory, or estimated execution time errors, consider materializing the endpoint. Materialization serves precomputed results on dedicated endpoint compute. Results are only as fresh as the last successful materialization.

Materialization does not reduce the query text size. For query_too_large, simplify the query.

See error responses for the response format and an example.

Capacity errors (503)

When the shared ClickHouse query pool reaches capacity, the API returns HTTP 503 with code: "query_capacity".

Example response:

JSON
{
  "type": "server_error",
  "code": "query_capacity",
  "detail": "Queries are momentarily at capacity — please retry shortly. For consistently heavy endpoints, materialize to run on dedicated endpoint compute that isn't affected by shared query load.",
  "attr": null
}

This error is temporary. Wait for the duration in the Retry-After response header before you retry. Limit the number of retries in your client.

For repeated capacity errors, consider materializing the endpoint to serve precomputed results on dedicated endpoint compute. Check that materialization completes before you use the stored results. Requests with refresh: "direct" still run the query against raw data.

Materialization errors

"Cannot materialize endpoint: ..."

The endpoint has variables that use unsupported operators or aren't in WHERE clauses. See variables and materialization for supported configurations
The endpoint is inactive

"Cannot enable materialization on inactive endpoint"

Activate the endpoint first, then enable materialization

Column type errors

"There's no column... in table. Not all column types are fully supported yet."

Some column types aren't fully supported yet
Try simplifying your query or casting columns to supported types

Slow responses

If endpoints are slow:

Check the Logs tab on the endpoint's page for duration_ms values
Look at the endpoints usage tab with the filter for the slow endpoint
Check if the underlying query is optimized
Consider materializing your endpoint
Review the query performance in the query log

Endpoints troubleshooting

Contents