# 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:

```json
{ "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](api.md#how-calls-are-authenticated).

## 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](../embed/viewer-tokens.md#errors) 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](limits.md#tenants-and-access). |
| `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](limits.md#tokens-and-sign-in). |
| `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](embed-sdk.md#what-the-viewer-sees). 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](settings.md#allowed-sites). |
| `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](../build-dashboards/connect-data.md#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](../build-dashboards/prepare-columns.md#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](limits.md#queries). |

### 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](../build-dashboards/push-api.md) 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](../embed/tenants-and-access.md), [Grant access to dashboards](../embed/grants.md), and [Install settings](settings.md).

| 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](../embed/grants.md#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.
