Skip to content
Not publicly available.This describes the Loupestack API before launch. Endpoints, limits and fields can still change.

Errors

Every endpoint under /v1/ answers errors in one shape:

{ "error": { "code": "query_not_allowed", "message": "table function not allowed: read_csv", "details": [] } }
  • code is stable and meant for programs. Branch on it, not on the status or the message.
  • message is for people and can change.
  • details is there only for some codes; for invalid_request it lists each problem with its path.

The login endpoints under /api/auth/ use Better Auth’s own shape, { "code", "message" } (Authentication).

This page is the list of codes. A test in the API fails when the API can answer with a code that is not on it.

Order. Who you are and what you may do are checked first, before the request body is read: whatever the body, a caller without a session gets 401 unauthenticated, someone without a workspace 403 no_workspace, and a member calling an owner/admin operation 403 admin_required. Only a caller who may call the operation gets 422 invalid_request for a body that does not match its schema.

Code Meaning
query_not_allowed The SQL of a saved query or a generated one is not a single read-only SELECT on the workspace’s own sources
alias_reserved That connector name is reserved: lake, memory, system and temp
host_not_allowed The connector’s host is a private or internal address
host_not_resolvable The connector’s host name does not resolve
ssl_required The connector must use TLS (sslMode: require)
credentials_not_allowed The BigQuery key points at something other than Google’s own endpoints
invalid_credentials The BigQuery key is not the JSON key of a service account
invalid_project The BigQuery project id is not valid
invalid_dataset The BigQuery dataset name is not valid
params_mismatch A saved query’s $name placeholders are not exactly its declared parameters
unknown_table No such table in this workspace’s sources
cursor_required An incremental sync job needs a cursorColumn
source_not_syncable This kind of connector cannot be synced yet (BigQuery); query it live instead
bad_request The request is malformed in a way not covered above (for example invalid JSON)
Status Code Meaning
401 unauthenticated No valid session: log in (Authentication)
403 no_workspace Logged in, but not a member of a workspace
403 admin_required Only owners and admins of the workspace may do this (for deleting a UI: also its creator)
403 csrf_check_failed A request other than GET without a trusted Origin header
Code Meaning
not_found No such route, or no such resource in your active workspace. A resource of another workspace is “not found” too.
Code Meaning
alias_in_use The workspace already has a connector with that name
description_exists That table already has a description; change it instead
target_in_use Another sync job already writes that lake table
saved_query_in_use A UI version still runs this saved query (internal API)
uploads_not_configured File sync jobs are not set up in this installation
slug_in_use That workspace slug is taken (internal API, provisioning)
tenant_not_provisioned The workspace has no data storage yet
run_finished That sync run was already reported finished (internal API, sync workers)

422: the request or its values were refused

Section titled “422: the request or its values were refused”
Code Meaning
invalid_request The body, path or query does not match the schema; details says where. Also: an invalid paging cursor
invalid_params The parameter values of a saved query do not match its declared parameters
query_failed The query was accepted but failed while running
Code Meaning
rate_limited Over a rate limit (Conventions); retry after retry-after seconds or a minute
too_many_queries The workspace has too many queries running at once
llm_busy The workspace has too many questions and UI generations in progress; wait for one to finish
Code Meaning
internal_error Something went wrong on our side. The message never contains details; retry later
Status Code Meaning
503 shutting_down The server is restarting; the request was interrupted. Retry
503 engine_busy All query engines are in use. Retry in a moment
503 llm_not_configured This installation has no language model configured
503 llm_unavailable The language model did not answer. Retry later
503 llm_timeout The language model did not answer in time (drafting a description)
503 llm_bad_output The language model’s answer was unusable (drafting a description). Retry
504 query_timeout The query took longer than the time limit
504 ask_timeout The question took longer than its time limit

A stream that has started reports a failure as an error event:

event: error
data: {"code":"no_answer","message":"I could not write a query that works for this question. Try rephrasing it or naming the table.","conversationId":"3d4e5f60-7182-4930-9c4d-5e6f7a8b9cad"}
Code Stream Meaning
no_answer ask, chat No working SQL after two repairs. Rephrase the question
no_ui UI, chat No usable UI after two repairs. Rephrase the prompt
ask_timeout ask, chat The question took longer than 60 seconds
ui_timeout UI, chat The generation took longer than 10 minutes
llm_timeout all The language model did not answer in time
llm_unavailable all The language model is not available
llm_bad_output all The language model’s answer was unusable
query_timeout ask, chat A query took longer than its time limit
too_many_queries ask, chat Too many queries running in the workspace
engine_busy ask, chat All query engines are in use
shutting_down all The server is restarting. Ask again
internal_error all Something went wrong on our side

A UI stream can also end with one of the codes from the tables above, for example tenant_not_provisioned. A query that the model wrote and that was refused or failed is not an error by itself: the model gets the reason and repairs its SQL, up to two times, before no_answer or no_ui.