Reference
Errors
Each error code a developer can meet, what it means, and what to do.
When GOAT refuses a request, it answers with an HTTP status and a JSON body:
{ "code": "TENANT_UNKNOWN", "message": "the tenant is not registered" }
Match on the call, the status, and code together: a few codes mean slightly different things on different calls, as the sections below show. The message is for people and may change. Some errors add fields, named in the tables below.
Each call takes one kind of credential: the token request and the push API take an API key, the admin calls take a person's own sign-in token, and the calls an embedded dashboard makes take a viewer token. See API.
Any call
| Status and code | What it means | What to do |
|---|---|---|
400 BAD_REQUEST | The body is not valid JSON or is not an object. On the token request, it also means the body has a field GOAT does not know, or is over 4 KiB. | Check the body. |
401 UNAUTHENTICATED | The call has no token, or its token is invalid or expired. | Send a valid credential of the kind the call takes. |
401 SESSION_EXPIRED | A person's sign-in is over 12 hours old. | Sign in again. |
403 EMBED_SCOPE | A viewer token was sent to a call viewers cannot make. | Send the kind of credential the call takes. |
403 ADMIN_REQUIRED | The call needs an Admin. | Ask an Admin. |
404 NOT_FOUND | The thing the call names does not exist, or you cannot see it. GOAT answers the same for both. | Check the id, and access. |
409 CONFLICT | The record changed since you read it. The body adds currentVersion. | Read it again, then resend with its new version in the If-Match header. |
413 PAYLOAD_TOO_LARGE | An admin call's body is over 1 MiB. | Send less. |
422 INVALID | A field's value is not allowed. The message says which. | Fix the value. |
429 RATE_LIMITED | Too many requests. | Wait the seconds in Retry-After, then retry. |
500 STORE_ERROR | GOAT could not read or write its records. | Retry. If it persists, ask whoever runs GOAT. |
503 UNAVAILABLE | GOAT is briefly unable to answer. | Retry shortly. |
Getting a viewer token
POST /v5/tokens/embed. See Viewer tokens for a sample request and what to do about each.
| Status and code | What it means |
|---|---|
401 API_KEY_INVALID | The API key is missing, wrong, or revoked. |
403 INSUFFICIENT_SCOPE | The key does not have the mint scope. |
400 INVALID_EXTERNAL_USER_ID_CHARSET | externalUserId holds : or /. |
400 INVALID_EXTERNAL_USER_ID_LENGTH | externalUserId is over 128 characters. |
422 INVALID_TOKEN_REQUEST | tenantId is missing, or a field's value is not allowed. |
422 INVALID_TIME_ZONE | The time zone is not one GOAT lists. |
404 TENANT_UNKNOWN | The tenant is not registered. |
422 INVALID_TENANT | The install registers new tenants on their first token request, and this tenant id breaks the rules for one. See Limits. |
403 TENANT_SUSPENDED | The tenant is suspended. |
429 RATE_LIMITED | The key asked for over 300 tokens in a minute, or over 20 at once. See Limits. |
503 EMBED_DISABLED | The install has no token signing set up. |
A successful answer may add warnings, with THEME_DROPPED when the theme asked for could not be used.
An embedded dashboard
GOAT answers these to the embed script, which shows the viewer a message. See Embed SDK. Most are fixed by the dashboard's author or whoever runs GOAT, not in your code.
| Status and code | What it means |
|---|---|
404 NOT_FOUND | The dashboard is not published, does not exist, or the tenant has no access. |
403 TENANT_UNKNOWN | The token's tenant is not registered. |
403 TENANT_SUSPENDED | The token's tenant is suspended. |
403 ORIGIN_DENIED | The page's site is not on the install's allowed sites. See Install settings. |
403 POINTER_ONLY | A viewer token asked to run a query of its own, which viewers cannot do. The embed script never sends one. |
403 RLS_REQUIRED | The chart's dataset has no tenant key (the column naming each row's customer), and its author has not shared it with every tenant. Ask the dashboard's author. See The tenant key. |
403 SENSITIVE_ACK_REQUIRED | A drill used a column classified PII or Sensitive, and the chart's author has not confirmed it may be used that way. Ask the author to open the chart, confirm, and save it. See What PII and Sensitive change. |
409 DATASET_PENDING | The chart's data is still loading, waiting for its first push, or failed to load. The body adds state. |
400 QUERY_FAILED | GOAT could not run the chart's query. Ask the dashboard's author to open the chart and check it. |
429 RATE_LIMITED | The tenant passed the query ceiling, which counts charts, metrics, and pages of rows together. The dashboard retries up to twice when Retry-After is 5 seconds or less. See Limits. |
The rows behind a chart
| Status and code | What it means |
|---|---|
403 ROWS_NOT_ALLOWED | Rows are off, either in the viewer token (reason: "token") or for every tenant by the install's settings (reason: "install"). |
403 ROWS_NOT_ENABLED | Rows are off for the chart (reason: "chart") or its dataset (reason: "dataset"). |
403 EXPORT_NOT_ALLOWED | The viewer token turns downloads off. |
403 DRILL_NOT_ALLOWED | The viewer token turns drilling off. |
409 COST_CAP | Reading these rows would pass the dataset's cost cap. Narrow them with filters. |
Sending rows (Push API)
POST /v5/dataload/datasets/{id}/ingest. See Push data from your application for a sample request.
| Status and code | What it means |
|---|---|
401 API_KEY_INVALID | The API key is wrong or revoked. |
403 INSUFFICIENT_SCOPE | The key does not have the ingest scope. |
400 NO_PUSH_SOURCE | The dataset is not a Push API dataset. |
400 EMPTY | The request sent no rows. |
503 REBUILDING, 503 DATASET_BUSY | The dataset is being rebuilt or loaded. Retry after Retry-After. |
502, with no code | The load failed. The body describes the load, and its errorCode says why. |
Tenants, grants, and settings
The calls are described in Tenants and access, Grant access to dashboards, and Install settings.
| Status and code | What it means |
|---|---|
422 INVALID_TENANT | The tenant id, attributes, or status is not valid, or the body has a field GOAT does not know. |
409 ALREADY_EXISTS | That tenant or grant already exists. |
413 REGISTER_TOO_LARGE | The call to /v5/admin/tenants/register sent over 1,000 tenant ids. |
413 SYNC_TOO_LARGE | The call to /v5/admin/tenants/sync sent over 1,000 rows. |
422 INVALID_SYNC | A sync row is not valid, an id appears twice, or the body has a field GOAT does not know. |
422 INVALID_GRANT | The tenant id, dashboard id, or level (VIEW or DENY) is not valid, or the body has a field GOAT does not know. |
422 INVALID_SELECTOR | A grant by tenant attributes names attributes or a level that are not valid, or the body has a field GOAT does not know. See Grant by tenant attributes. |
422 FILTER_DOMAIN_REQUIRED | This would be the dashboard's first grant, and one of its filters has no list of allowed choices yet. The body adds attachments. Ask the author to set the filter's choices, then grant again. |
422 SENSITIVE_ACK_REQUIRED | This would be the dashboard's first grant, and one of its filters uses a column classified PII or Sensitive. The body adds requires.sensitiveAttachAck and attachments. Resend with "sensitiveAttachAck": true to confirm. |
409 GRANT_SLOT_CONFLICT | The grant clashes with one the tenant already holds for that dashboard. |
422 SELECTOR_CAP | The install already has 100 grants by tenant attributes. |
400 BAD_IF_MATCH | The If-Match header is not a version number. |
The settings call ignores fields it does not know, so check the spelling of each name.