Skip to main content

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 codeWhat it meansWhat to do
400 BAD_REQUESTThe 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 UNAUTHENTICATEDThe call has no token, or its token is invalid or expired.Send a valid credential of the kind the call takes.
401 SESSION_EXPIREDA person's sign-in is over 12 hours old.Sign in again.
403 EMBED_SCOPEA viewer token was sent to a call viewers cannot make.Send the kind of credential the call takes.
403 ADMIN_REQUIREDThe call needs an Admin.Ask an Admin.
404 NOT_FOUNDThe thing the call names does not exist, or you cannot see it. GOAT answers the same for both.Check the id, and access.
409 CONFLICTThe 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_LARGEAn admin call's body is over 1 MiB.Send less.
422 INVALIDA field's value is not allowed. The message says which.Fix the value.
429 RATE_LIMITEDToo many requests.Wait the seconds in Retry-After, then retry.
500 STORE_ERRORGOAT could not read or write its records.Retry. If it persists, ask whoever runs GOAT.
503 UNAVAILABLEGOAT 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 codeWhat it means
401 API_KEY_INVALIDThe API key is missing, wrong, or revoked.
403 INSUFFICIENT_SCOPEThe key does not have the mint scope.
400 INVALID_EXTERNAL_USER_ID_CHARSETexternalUserId holds : or /.
400 INVALID_EXTERNAL_USER_ID_LENGTHexternalUserId is over 128 characters.
422 INVALID_TOKEN_REQUESTtenantId is missing, or a field's value is not allowed.
422 INVALID_TIME_ZONEThe time zone is not one GOAT lists.
404 TENANT_UNKNOWNThe tenant is not registered.
422 INVALID_TENANTThe install registers new tenants on their first token request, and this tenant id breaks the rules for one. See Limits.
403 TENANT_SUSPENDEDThe tenant is suspended.
429 RATE_LIMITEDThe key asked for over 300 tokens in a minute, or over 20 at once. See Limits.
503 EMBED_DISABLEDThe 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 codeWhat it means
404 NOT_FOUNDThe dashboard is not published, does not exist, or the tenant has no access.
403 TENANT_UNKNOWNThe token's tenant is not registered.
403 TENANT_SUSPENDEDThe token's tenant is suspended.
403 ORIGIN_DENIEDThe page's site is not on the install's allowed sites. See Install settings.
403 POINTER_ONLYA viewer token asked to run a query of its own, which viewers cannot do. The embed script never sends one.
403 RLS_REQUIREDThe 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_REQUIREDA 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_PENDINGThe chart's data is still loading, waiting for its first push, or failed to load. The body adds state.
400 QUERY_FAILEDGOAT could not run the chart's query. Ask the dashboard's author to open the chart and check it.
429 RATE_LIMITEDThe 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 codeWhat it means
403 ROWS_NOT_ALLOWEDRows are off, either in the viewer token (reason: "token") or for every tenant by the install's settings (reason: "install").
403 ROWS_NOT_ENABLEDRows are off for the chart (reason: "chart") or its dataset (reason: "dataset").
403 EXPORT_NOT_ALLOWEDThe viewer token turns downloads off.
403 DRILL_NOT_ALLOWEDThe viewer token turns drilling off.
409 COST_CAPReading 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 codeWhat it means
401 API_KEY_INVALIDThe API key is wrong or revoked.
403 INSUFFICIENT_SCOPEThe key does not have the ingest scope.
400 NO_PUSH_SOURCEThe dataset is not a Push API dataset.
400 EMPTYThe request sent no rows.
503 REBUILDING, 503 DATASET_BUSYThe dataset is being rebuilt or loaded. Retry after Retry-After.
502, with no codeThe 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 codeWhat it means
422 INVALID_TENANTThe tenant id, attributes, or status is not valid, or the body has a field GOAT does not know.
409 ALREADY_EXISTSThat tenant or grant already exists.
413 REGISTER_TOO_LARGEThe call to /v5/admin/tenants/register sent over 1,000 tenant ids.
413 SYNC_TOO_LARGEThe call to /v5/admin/tenants/sync sent over 1,000 rows.
422 INVALID_SYNCA sync row is not valid, an id appears twice, or the body has a field GOAT does not know.
422 INVALID_GRANTThe tenant id, dashboard id, or level (VIEW or DENY) is not valid, or the body has a field GOAT does not know.
422 INVALID_SELECTORA 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_REQUIREDThis 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_REQUIREDThis 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_CONFLICTThe grant clashes with one the tenant already holds for that dashboard.
422 SELECTOR_CAPThe install already has 100 grants by tenant attributes.
400 BAD_IF_MATCHThe If-Match header is not a version number.

The settings call ignores fields it does not know, so check the spelling of each name.

GOAT documentation

Type to search.