Common Query Errors

This page describes common errors you may encounter when using the Aito API and how to resolve them.

Unknown Field

Error message: Unknown field 'fieldName' in table 'tableName'

Cause: The field name specified in your query doesn't exist in the table schema.

Solutions:

  • Check the field name spelling (field names are case-sensitive)
  • Use the schema endpoint to verify available fields: GET /api/v1/schema/{table}
  • For linked table fields, use dot notation: product.name instead of productName
// Wrong - field doesn't exist
{ "from": "products", "where": { "productName": "coffee" } }

// Correct - use the actual field name
{ "from": "products", "where": { "name": "coffee" } }

Unknown Table

Error message: Unknown table 'tableName'

Cause: The table specified in your query doesn't exist in the database.

Solutions:

  • Check the table name spelling (table names are case-sensitive)
  • Use the schema endpoint to list all tables: GET /api/v1/schema
  • Ensure the table was created before querying

Missing Required Field

Error message: Missing required field 'fieldName'

Cause: A required parameter is missing from your query.

Solutions:

  • Check the API documentation for required parameters
  • Common required fields:
    • from - the table to query
    • predict - the field to predict (for prediction queries)
    • recommend - the field to recommend (for recommendation queries)
// Wrong - missing 'from'
{ "where": { "name": "coffee" } }

// Correct
{ "from": "products", "where": { "name": "coffee" } }

Type Mismatch

Error message: Type mismatch: expected 'expectedType', got 'actualType'

Cause: The value type doesn't match what the field expects.

Solutions:

  • Use strings for text fields: "value" not value
  • Use numbers for numeric fields: 42 not "42"
  • Use booleans for boolean fields: true not "true"
  • Use arrays for array fields: ["a", "b"] not "a, b"
// Wrong - price should be a number
{ "from": "products", "where": { "price": "3.95" } }

// Correct
{ "from": "products", "where": { "price": 3.95 } }

Empty Candidate Set

Error message: Empty candidate set or No matching rows

Cause: Your query filters returned no results.

Solutions:

  • Broaden your search criteria
  • Check if the values you're filtering by exist in the data
  • Use $match for fuzzy text matching instead of exact match
  • Verify the data has been uploaded to the table
// Exact match might return nothing
{ "from": "products", "where": { "name": "coffee" } }

// Fuzzy match is more flexible
{ "from": "products", "where": { "name": { "$match": "coffee" } } }

Invalid JSON Syntax

Error message: Invalid JSON at line X, column Y

Cause: The query body contains invalid JSON.

Common mistakes:

  • Missing commas between fields
  • Trailing commas after the last field
  • Unquoted strings
  • Single quotes instead of double quotes
  • Missing closing brackets
// Wrong - missing comma
{ "from": "products" "where": { "name": "coffee" } }

// Wrong - trailing comma
{ "from": "products", "where": { "name": "coffee", } }

// Correct
{ "from": "products", "where": { "name": "coffee" } }

Unknown Operator

Error message: Unknown operator '$operatorName'

Cause: The query uses an operator that doesn't exist.

Solutions:

  • Check the operator spelling (operators are case-sensitive)
  • Operators must start with $
  • See the Query Language documentation for available operators

Common operators:

  • $match - full-text search
  • $has - array contains value
  • $gt, $gte, $lt, $lte - numeric comparisons
  • $and, $or, $not - logical operators

Linked Table Not Found

Error message: Linked table 'tableName' not found

Cause: The query references a linked table that doesn't exist or isn't properly linked.

Solutions:

  • Verify the linked table exists
  • Check that the link is properly defined in your schema
  • Use the correct link field name

Rate Limit Exceeded

Error message: Rate limit exceeded

Cause: Too many requests in a short time period.

Solutions:

  • Reduce request frequency
  • Use batch queries to combine multiple operations
  • Implement exponential backoff for retries
  • Contact support for higher rate limits if needed

Query Timeout

Error message: Query timeout or Request timeout

Cause: The query took too long to execute.

Solutions:

  • Add limit to reduce result set size
  • Use more specific where conditions
  • For long-running queries, use the Jobs API: POST /api/v1/jobs/{query}
  • Optimize your data structure and indexes
// Add limit to prevent timeout
{
  "from": "large_table",
  "where": { "status": "active" },
  "limit": 100
}