Make a question answerable
The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.
Use an Ask error’s details to make the question more specific. Repeating an unchanged question will not resolve missing context.
Before you run it: Branch on the error code, not the wording of a hint. Avoid sending secrets in questions to a configured model provider.
The nonsense question below is deliberately invalid; it is not a setup test. First confirm that the row-count example works with your connection. Then compare this refusal with a meaningful question about those same customers.
- Read the error codeIdentify why the question could not produce a plan.
- Check the tableConfirm its name, columns and available data.
- Rewrite the questionAsk for one clear count or filter.
- Verify the new planCheck the corrected read before using its answer.
Follow the example
- Read the stable error code.
- Check table and column names.
- Add a schemas hint or rewrite the question.
- Retry and inspect the result.
Run the request
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "nl": "ufnwiefwn wefjwe" }'Check the result
The failed example returns no_plan_compiled with a hint and suggested rephrase.
HTTP/1.1 400 Bad Request
{
"error": "no_plan_compiled",
"hint": "the question contained no recognisable identifiers (table, column, or relation name). nothing in the registered schemas matched any token.",
"suggested_rephrase": "ask in terms of names that appear in your schemas - e.g. \"how many shop.customers do I have\""
}error is stable - branch on it in your code. hint and suggested_rephrase are human-readable and may change wording between releases; show them, don't parse them.
Understand the behavior
- The compiler tokenises the question and tries to bind tokens to schema identifiers (namespace, table, column, relation name).
- If too few tokens bind, the compiler refuses to guess. There is no silent fallback to "scan everything".
- The hint explains the binding failure in human terms; the suggested rephrase uses identifiers from the visible catalog as anchor words.
- A failed compile is not cached - retry safely with a better question.
Important limits and checks
- Ambiguous column references. "Total by month" with no date column anywhere in the visible schemas is unanchored - say which column to bucket by.
- Sensitive data in questions. The LLM-fallback path (if configured) sees the full question. Don't put PII, secrets, or credentials in the
nlfield - bind those as parameters in/v1/queryinstead. - Retrying without rephrasing. The error is deterministic for a fixed schema set. Retrying the same question gets the same error. Either rephrase or change the schemas list (or registered schemas).