Error Codes Reference

Use this page to look up any error string you see in an embed, the metric builder, or a guest-token API response.

Embed runtime errors

These surface when an embedded dashboard or metric loads. Guest tokens are database-backed UUIDs, not signed JWTs — there is no signing key, so none of these errors are about signatures.

Error	Meaning	Fix
`INVALID_TOKEN`	The token UUID was not found in the deployment being queried	Check for a cloud vs self-hosted mismatch (a token exists only in the environment that minted it); confirm the embed receives the exact minted value; mint a fresh token
`TOKEN_EXPIRED`	The token exists but its `expiryTime` has passed	Mint a fresh token; refresh cached tokens before the deadline. Tokens without `expiryTime` never expire
`UNAUTHORIZED_ORIGIN`	The page’s origin is not on the Whitelist Domains list	Add the origin (scheme-less `host[:port]`, wildcards like `.example.com` supported) under your Data App’s settings → Whitelist Domains. Whitelist your* domain, not `api.usedatabrain.com`. The list is account-wide
`UNAUTHORIZED`	The token is not allowed this request. On dashboard load: the ID isn’t in the token’s `params.allowedEmbeds`, or the dashboard doesn’t belong to the token’s Data App/workspace. On dashboard-filter or dashboard-view requests: that capability isn’t granted	For load errors: fix `allowedEmbeds` or the ID. For filter/view errors: enable End User Dashboard Filter / Create Dashboard View in the Data App’s Access Control, or grant it in the token (`params.accessPermissions.isAllowEndUserDashboardFilter`, `permissions.isEnableCreateDashboardView`)
`INVALID_ID`	The dashboard/embed ID does not belong to the token’s Data App	Verify the ID and that the token was minted for the right Data App
`UNAUTHORISED REQUEST!`	The request is missing a valid plugin token header	Ensure the embed component receives a `token` attribute

Metric execution errors (E1001–E1007)

Code	Message	Cause & fix
`E1001`	`Filter or Client variables detected in the query.`	The final SQL still contains an unresolved `{{…}}` token at execution. Causes: variable name doesn’t match the filter’s variable name (case-sensitive); the filter has no value or default; no matching filter is attached. Fix the name and give the filter a default value. See Filter Troubleshooting
`E1002`	`Metric data or query could not be found.`	The metric’s stored query is missing — re-save the metric
`E1003`	`Drill-down query execution failed.`	The drill-down query errored — check the underlying SQL
`E1004`	`Invalid query or insufficient permissions to access it.`	The query failed validation or the caller lacks access
`E1005`	`An error occurred while fetching data from the database.`	The data source returned an error — test the connection and run the SQL directly against the source
`E1006`	`Forecast query execution failed.`	The forecast service errored on this metric
`E1007`	`Hasura server error occurred while processing the request.`	Internal metadata-layer error — on self-hosted check the hasura service; on cloud contact support

Multi-select filter variables substitute as a parenthesized quoted list (e.g. ( 'US' , 'CA' )). Write WHERE col IN {{var}} without your own parentheses — IN ({{var}}) double-wraps into invalid SQL.

Guest-token API errors (mint time)

Returned by POST /api/v2/guest-token/create. See the Guest Token reference for the accepted payload.

Code	Meaning
`AUTHENTICATION_ERROR`	Invalid or missing API key in the `Authorization` header
`INVALID_REQUEST_BODY`	The body failed validation — includes any unknown field (`dataAppId`, `client_id`, `tenant_id`, `permissions.dashboards` are not valid fields)
`INVALID_DATA_APP_NAME`	`dataAppName` doesn’t match any Data App (case-sensitive)
`CLIENT_ID_ERROR`	Invalid `clientId` value
`WORKSPACE_ID_ERROR`	Workspace not found or inaccessible
`DASHBOARD_PARAM_ERROR` / `EMBED_PARAM_ERROR`	Invalid dashboard/embed parameters
`APP_FILTER_PARAM_ERROR`	Invalid `params.appFilters` shape
`RLS_SETTINGS_PARAM_ERROR`	Invalid `params.rlsSettings` shape
`DATASOURCE_NAME_ERROR` / `DATAMART_NAME_ERROR`	`datasourceName` / `datamartName` doesn’t resolve
`UNSUBSCRIBED_ACCOUNT_ERROR`	The account’s subscription doesn’t allow this operation
`INTERNAL_SERVER_ERROR`	Server-side failure — retry, then contact support

Browser-side errors

`QuotaExceededError … 'metric-data' exceeded the quota`

The embed plugin caches metric data in localStorage, and a large metric blew past the browser’s per-origin quota (~5–10 MB).

Clear the key: window.localStorage.removeItem('metric-data') and reload.
Reduce the row/column count of the offending metric (LIMIT, pagination, or split it).

This is a browser storage limit — it is unrelated to API rate limits, and the self-hosted RATE_LIMIT env var has no effect on it.

Rate limiting (HTTP 429)

Cloud API requests are throttled per Data App. Back off using the Retry-After header and cache read-heavy calls. See Rate Limiting.

​Embed runtime errors

​Metric execution errors (E1001–E1007)

​Guest-token API errors (mint time)

​Browser-side errors

​QuotaExceededError … 'metric-data' exceeded the quota

​Rate limiting (HTTP 429)

Embed runtime errors

Metric execution errors (E1001–E1007)

Guest-token API errors (mint time)

Browser-side errors

`QuotaExceededError … 'metric-data' exceeded the quota`

Rate limiting (HTTP 429)