Errors and corrections

Every failure is JSON with one shape, and the class tells you whose fault it is: the envelope, the key, the spec, or the model. Successful responses may also carry a corrections array when a misspelled field was silently matched. This page lists both so your application can act on them.

The envelope

{"error": {"class": "FieldNotFound", "message": "No field named 'revenu' in this model. Did you mean: Revenue, Net Paid?"}}

class is stable and meant for code; message is for people and may name fields from the model.

Classes and statuses

400 means fix the request envelope; 401/403 means fix the key or its grants; 422 means fix the spec or the model; 5xx is ours.

Messages you will meet

Envelope and auth

Field references

Spec shape (InvalidSpec)

Validation (InvalidValue)

All prefixed Validation failed: .

A bad calculation data_type (outside string, integer, decimal, date, date_time, boolean, bigint, binary) and a window size, offset or buckets below 1 are rejected in the same class.

Planner

Shorthand (Shorthand, 400)

The corrections array

A field reference that matches nothing exactly is scored against every field of the wanted kind by trigram overlap of the normalized text (lower-cased, runs of non-alphanumerics collapsed to one space) against the field’s name, uid and synonyms. Three constants decide what happens:

When both hold the candidate is used silently and the response reports it:

{"sql": "...", "datasource": "Warehouse", "datasource_uid": "warehouse", "adapter": "postgres",
 "corrections": [{"term": "departmnt", "field_uid": "department", "field_name": "Department", "score": 0.8}]}

corrections is omitted when empty. When the floor or the margin is not met, the request fails with FieldNotFound and up to three candidates scoring at least 0.25 in Did you mean: A, B, C?.

zsql prints corrections to stderr before the SQL, one per line:

departmnt → Department (~0.8)

Treat a correction as a warning in an interactive tool (show the user what was substituted) and as an error in a pipeline, where a silently substituted field is a bug waiting to be noticed.

Handling errors in your app

async function plan(body) {
  const res = await fetch(`https://app.0sql.io/projects/tpcds/branches/main/sql`, {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const json = await res.json();

  if (!res.ok) {
    const { class: cls, message } = json.error;
    switch (cls) {
      case "FieldNotFound":
      case "FieldAmbiguous":
      case "InvalidSpec":
      case "InvalidValue":
      case "Shorthand":
        throw new UserFixable(message);        // show it; the request can be edited
      case "Unresolvable":
      case "SecurityPolicy":
      case "Unimplemented":
        throw new ModelProblem(message);       // the model or the policy needs a change
      case "ContextRequired":
      case "Invalid":
      case "Unauthorized":
      case "Forbidden":
      case "NotFound":
        throw new IntegrationBug(cls, message); // your code built the request or key wrong
      default:
        throw new Error(`${cls}: ${message}`);  // 5xx: retry later, then report it
    }
  }

  if (json.corrections?.length) {
    log.warn("0sql corrected fields", json.corrections);
  }
  return json; // { sql, datasource, datasource_uid, adapter, ... }
}

Three habits that pay off:

• Branch on class, never on message. Messages name fields and may change wording.
• Surface FieldNotFound with its Did you mean candidates and FieldAmbiguous with its @d/@m hint directly to whoever is building the query; they are written to be shown.
• Log corrections with the request. A rename in the model can turn an exact match into a fuzzy one without any error.

Next steps

• The query spec
• Field references
• Troubleshooting