DATASOURCE_OFFLINE | Datasource has status='offline'. | Don't retry. Surface to the user; pick a different datasource. |
EXTRACT_STALE (warning) | now − lastRefreshedAt > freshnessSlaSeconds. Returned alongside a successful response. | Use the data; disclose staleness to the user. Don't retry. |
QUERY_TIMEOUT | Query exceeded LOOKOUT_QUERY_WALL_MS (default 5s). | Narrow the filter, shrink the time window, then retry. |
RESULT_TOO_LARGE | Caller pegged rowLimit at the cap and the result still exceeded it. | Add filters OR call export_view_csv for full results. |
INVALID_FILTER | Filter references unknown field, incompatible op, or malformed value. | Don't retry. Read details.field; fix the filter. |
SQL_FORBIDDEN_CONSTRUCT | INSERT/UPDATE/DELETE/multi-statement/foreign-table reference detected. | Don't retry. Rewrite as a single SELECT against data. |
SQL_PARSE_ERROR | SQLite couldn't parse the query. | Don't retry. Read error.message; fix the SQL. |
CHART_TYPE_UNSUPPORTED | render_view against a chartType not in the supported set. | Don't retry render. Fall back to query_view_data and describe textually. |
*_NOT_FOUND | Resource doesn't exist or is soft-deleted. | Don't retry. Re-list and pick a valid one. |
INVALID_INPUT | Input failed JSON-Schema validation. | Don't retry. Read details.errors[].path; fix that field. |
INVALID_PAGE_SIZE | pageSize out of range. | Don't retry. Use a value in [1, 100]. |
INVALID_CURSOR | Cursor malformed or wrong resource type. | Don't retry the same cursor. Restart pagination from no cursor. |
RESPONSE_TRUNCATED (warning) | Final-envelope guard trimmed the rows array. | Filter further or call export_view_csv. |
ENVELOPE_TOO_LARGE | Response > 256 KB and not a row-shaped response that could be trimmed. | Tighten filters; investigate seed data if it's a get_view. |
RATE_LIMITED (reserved) | Reserved for future use; not enforced in v1. | Backoff + retry with jitter. |
TOOL_NOT_FOUND | Tool name not in the registry. | Don't retry. Re-read tools/list. |
INTERNAL_ERROR | Uncaught exception in a tool. | Retry once with backoff; otherwise escalate — server bug. |