Errors
The errors below are specific to TagoSQL queries. Standard API errors (authentication, rate limiting, per-endpoint status codes) behave as they do everywhere else; see the TagoIO API reference.
Query problems (400)
Fix the query or the request:
| Trigger | Example message |
|---|---|
| SQL syntax error or disallowed construct | Invalid query |
| Inactive query executed | SQL query is inactive |
Written LIMIT above the plan row cap | LIMIT exceeds the plan row cap (100). Lower it and paginate with OFFSET |
Result exceeds the row cap (query had no LIMIT) | Result exceeds the 100-row limit. Add LIMIT (and OFFSET to paginate) |
Missing, extra, duplicate, or gapped $n parameter | Message naming the $n token |
| Parameter value invalid for how the query uses it | Invalid value for parameter $1 |
| Fleet query without the required filters | device_data_by_tag requires a variable = '<name>' filter |
| Fleet time bound older than the plan window | time bound exceeds the 90-day window allowed on your plan |
| Fleet tag filter matching too many devices | Tag filter matches more than 100 devices. Narrow the tags or paginate with after_device |
Session context (400)
Raised by session functions. Some are checked when you save the query, others when it runs:
| Trigger | Message |
|---|---|
session_user_tag called with the wrong number of arguments | session_user_tag takes exactly one argument, the literal tag key |
A malformed COALESCE around a session function | COALESCE with a session function takes exactly two arguments: the session function first, a non-empty string fallback second |
| The profile owner runs a session function that has no fallback | session_user_tag('customer') has no value for profile execution |
| An analysis runs a query that uses session context | This query uses session context and requires a Run User |
| A user's tag key resolves to more than one value | User tag 'customer' resolves to multiple values |
| A session query run outside stored query execution | Session functions are only available on stored query execution |
A session function in a disallowed position, with a non-literal argument, or wrapped in a malformed
COALESCE is rejected when you save the query. Whether the running caller is allowed (owner, Run user, or
analysis) is decided when the query runs.
Plan limits (402)
Raised by upgrading the plan (or lowering usage): the stored-query cap, the per-query parameter cap, JOINs
on the Free plan (JOINs require a Starter plan or above), too many joined tables, and an exhausted monthly
data output allocation.
Not found (404)
| Trigger | Example message |
|---|---|
| Query id not on your profile (including someone else's) | SQL Query can't be found |
| Version not in the query's history | 404 |
| Device or entity not owned or nonexistent | Device 'x' not found |
| Device exists but has never stored data | Device 'x' has no data |
| Fleet tag filter matching no device | No device found with tag |
Ownership failures are always 404, never 403: a resource you cannot access is indistinguishable from one
that does not exist.
These not-found errors apply to literal values written in the query text. A value resolved from the user
session that matches nothing returns an empty 200 result instead, so a resolved value never appears in an
error message. See Session Context.
Timeout (408)
The query exceeded your plan's execution timeout: Query timed out (15s limit). Narrow the time range, add
tighter filters, or reduce the number of joined tables.