> ## Documentation Index > Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes Reference > Every error string DataBrain can return — embed runtime errors, metric execution errors (E1001–E1007), and guest-token API errors — with cause and fix. 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](/guides/dashboards/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](/developer-docs/helpers/api-reference/token) 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). 1. Clear the key: `window.localStorage.removeItem('metric-data')` and reload. 2. 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](/developer-docs/rate-limiting).