Errors

Every error has the same format:

{
  "code": "sql_rejected",
  "message": "The generated SQL query was rejected.",
  "details": { "violations": [{ "code": "unknown_column", "params": {} }] }
}

• code is stable and in English. Program against it.
• message is translated into the resolved language (locale → Accept-Language → tenant default → pt-BR) and can be shown to the user, but its text may change.
• details carries extra data, which varies by code.

Every response, success or error, carries the X-Request-ID header (req_…). Record it in your logs and include it when asking for support.

Codes

HTTP	code	Meaning and action
400	end_user_required	The tenant requires end_user and the question came without it.
401	invalid_api_key	Header missing, malformed, key does not exist or was revoked. Do not repeat without fixing it.
404	request_not_found	Unknown request_id, belongs to another tenant or cannot be rated (feedback and history).
404	not_found	Route does not exist.
405	method_not_allowed	HTTP method not accepted by the route (see the Allow header).
409	schema_not_configured	The tenant has not registered the DDL in the panel yet.
409	llm_not_configured	The tenant has not configured the LLM provider, model and key.
409	unsupported_llm_provider	The saved provider is no longer accepted; the administrator needs to change it.
409	secret_unreadable	The saved LLM key can no longer be read; the administrator needs to register it again.
413	payload_too_large	Body above 96 KiB.
422	invalid_request	Invalid body or query, or unknown field. details.fields lists the fields.
422	invalid_end_user	end_user in the wrong format: looks like an email or a name, contains spaces or is too short.
422	question_too_long	Question above 2,000 characters (details.limit).
422	invalid_max_rows	Invalid max_rows.
422	prompt_too_large	Schema, context and examples do not fit in the prompt. Tell the administrator.
422	no_answer	The LLM concluded that the schema does not answer the question. Ask the user to rephrase.
422	sql_rejected	The generated SQL did not pass the SQL Guard, even after the automatic correction. details.violations is a list of {code, params} with generic codes.
422	invalid_feedback	Invalid rating in /v1/feedback.
429	rate_limited	Request limit reached. details.scope = "end_user" when the limit is the end user's. Respect Retry-After.
500	internal_error	Unexpected error. Send the X-Request-ID to support.
502	llm_error	Failure of the tenant's LLM. See details.reason below.
503	service_unavailable	Platform database unreachable or overloaded. Comes with Retry-After.
503	not_ready	Service without database access; try again.

sql_rejected

So as not to reveal what your administrator hid, hidden tables and columns appear as unknown_table and unknown_column, and column names are never returned. The real reason stays in the panel's History. Rephrasing the question usually solves it; if a legitimate question is rejected often, add an example for it in the panel.

llm_error and details.reason

reason	Action
timeout, llm_unavailable, llm_rate_limited	Transient: try again with backoff.
invalid_llm_key, invalid_model	The administrator needs to fix the LLM configuration in the panel.
empty_response, invalid_response	The LLM returned something unusable; try again or rephrase.

Suggested retry policy

Situation	What to do
429	Wait the number of seconds in Retry-After before repeating.
502 with a transient reason, 503	Exponential backoff (1 s, 2 s, 4 s), at most 3 attempts.
401, 409, 422	Do not repeat the same request.
Timeout of your HTTP client on /v1/ask	Do not retry automatically: each attempt spends tokens. Let the user try again.