# Errors

> The one error envelope every /v1 path uses, the error string format, every status from 400 to 503, which ones to retry, and every error token per endpoint.

Source: https://docs.getbeekon.com/api/errors/

Every `/v1` error is an HTTP status and a one-member JSON body. This page lists what each status means, whether to retry, and every error string each endpoint can return.

```sh
curl -s -w '%{http_code}\n' https://api.in1.getbeekon.com/v1/project   # no token
# {"error":"missing bearer token"}
# 401
```

## The envelope

Every error is a JSON object with one member:

```json
{"error":"insufficient scope"}
```

* `Content-Type: application/json`.
* `error` is a short, stable string. Match it **verbatim**: it is part of the contract, and its text does not change within `/v1`.
* The body ends with a newline today. Do not depend on it either way.

This holds for every path under `/v1`, including ones that do not exist:

* A path no endpoint serves answers `404` with `{"error":"not found"}`, the same body as an unknown id. “No such endpoint” and “no such resource” read alike.
* A method an existing path does not serve (say `DELETE /v1/project`) answers `405` with `{"error":"method_not_allowed"}`, and an `Allow` header lists the methods the path does serve, for example `Allow: GET, HEAD`. `HEAD` is listed wherever `GET` is.

Both are decided before any other check, so they answer the same with or without a token. On a path that exists, with a method it serves, the [order of checks](https://docs.getbeekon.com/api/scopes/#the-order-of-checks) applies: an unknown id behind a valid path is still `401` first when the token is missing.

## Error string format

The error string has one of three shapes:

* **A `snake_case` token**, such as `invalid_window`, `invalid_body`, `expired_cursor` or `quota_fences`. Used by every error not in the third shape below. It names the parameter or rule: `invalid_<parameter>` for a bad parameter or member, a rule name for a conflict.
* **`invalid_config: <paths>`**, such as `invalid_config: sync.batch_size, tracking.accuracy_mode`. The remote-config document only. **Prefix-match** `invalid_config:`; the rest lists every offending member as a dotted path, in ASCII order, separated by `", "`.
* **A short phrase**, such as `insufficient scope`, `not found`, `internal error` or `missing bearer token`. The authentication, permission, lookup (`404 not found`) and server-failure answers shared by every endpoint, the paging message `limit must be an integer in [1, 500]`, and every [ingest](https://docs.getbeekon.com/api/ingest/#errors) error, such as `invalid batch`.

## Status codes

| Status | Meaning                                                                                                                                                                                                                                                               | What to do                                                                                                                                                                        |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request is invalid. The token names the parameter or rule.                                                                                                                                                                                                        | Fix the request. Do not retry it unchanged.                                                                                                                                       |
| `401`  | No session, or the session token is expired or invalid.                                                                                                                                                                                                               | Mint a new token and retry once. See [Authentication](https://docs.getbeekon.com/api/authentication/).                                                                                                      |
| `403`  | The session is not allowed here: wrong key kind, or a missing [scope](https://docs.getbeekon.com/api/scopes/).                                                                                                                                                                                  | Use a key with the right scope. Retrying will not help.                                                                                                                           |
| `404`  | `not found`: the id does not exist **in your project**. An unknown id, another project’s id and a malformed UUID id (geofence, trip, webhook) all get the same answer, and so does a path no endpoint serves. A malformed `user_id` is `400 invalid_user_id` instead. | Check the id and the path.                                                                                                                                                        |
| `405`  | `method_not_allowed`: the path exists, but not with this HTTP method. The `Allow` header lists the methods it serves.                                                                                                                                                 | Use one of the `Allow` methods. Retrying will not help.                                                                                                                           |
| `409`  | A conflict the endpoint defines, such as a quota.                                                                                                                                                                                                                     | Resolve the conflict (delete something, wait for commands to expire).                                                                                                             |
| `410`  | `expired_cursor`: the data your cursor pointed into has been deleted under your plan’s retention.                                                                                                                                                                     | Restart the walk. See [Pagination](https://docs.getbeekon.com/api/pagination/#expired-cursors-410).                                                                                                         |
| `412`  | `precondition_failed`: your `If-Match` names a revision that is no longer current.                                                                                                                                                                                    | Re-read, re-apply your change, write again. See [Remote config](https://docs.getbeekon.com/api/remote-config/#concurrent-writers-etag-and-if-match).                                                        |
| `413`  | `too_large`: the request body is over the endpoint’s cap.                                                                                                                                                                                                             | Send a smaller body.                                                                                                                                                              |
| `429`  | Rate limited. A `Retry-After` header (in seconds) is present.                                                                                                                                                                                                         | Wait at least `Retry-After`, then retry the same request. See [Rate limits](https://docs.getbeekon.com/api/rate-limits/).                                                                                   |
| `500`  | `internal error`: a failure on our side, including a region we could not reach.                                                                                                                                                                                       | Retry with exponential backoff, **keeping your cursor**.                                                                                                                          |
| `503`  | The service is briefly unable to take the request. A `Retry-After` header (in seconds) is present.                                                                                                                                                                    | Retry after `Retry-After`. Two ingest answers are not brief: `unsupported schema_version` and `project suspended`. Do not retry those blindly. See [Ingest](https://docs.getbeekon.com/api/ingest/#errors). |

**A server-side failure is always `5xx`, never `4xx`.** In particular, a `400` about a cursor is always about the cursor you sent; it is never caused by an outage. Of all statuses, only `410` tells you to abandon a cursor.

A request with more than one problem may be reported as any one of them, except that the checks run in a fixed order (authentication, key kind and scope first). See [the order of checks](https://docs.getbeekon.com/api/scopes/#the-order-of-checks).

## Exact bodies

These bodies are byte-exact (before the trailing newline).

| Status | Body                                               | When                                                                                                                                                                                  |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `{"error":"invalid_body"}`                         | A JSON body that is not one object, has an unknown member, a wrong type or a duplicate key. See [Conventions](https://docs.getbeekon.com/api/conventions/#request-bodies-are-strict).                           |
| 400    | `{"error":"limit must be an integer in [1, 500]"}` | A bad `limit` on any list, or a repeated one on any list except `GET /v1/events`, which reads the first.                                                                              |
| 400    | `{"error":"invalid_cursor"}`                       | A cursor this server did not issue for this list.                                                                                                                                     |
| 401    | `{"error":"missing bearer token"}`                 | No `Authorization: Bearer …` header, or an empty one.                                                                                                                                 |
| 401    | `{"error":"invalid session token"}`                | The token is expired, malformed, or from another region.                                                                                                                              |
| 403    | `{"error":"server credentials required"}`          | A session minted from an SDK key, on every server endpoint except `/v1/locations` and `/v1/events` (their own bodies are below) and `POST /v1/ingest` (which accepts an SDK session). |
| 403    | `{"error":"insufficient scope"}`                   | The key lacks the endpoint’s scope. Names no scope.                                                                                                                                   |
| 404    | `{"error":"not found"}`                            | An unknown or foreign id, a malformed UUID id (geofence, trip, webhook), or a path no endpoint serves.                                                                                |
| 405    | `{"error":"method_not_allowed"}`                   | A method the path does not serve. Carries `Allow`.                                                                                                                                    |
| 409    | `{"error":"webhook_limit_reached"}`                | A project’s 11th webhook endpoint.                                                                                                                                                    |
| 409    | `{"error":"too_many_active_commands"}`             | A device’s 21st active command.                                                                                                                                                       |
| 410    | `{"error":"expired_cursor"}`                       | A cursor below the retention floor.                                                                                                                                                   |
| 412    | `{"error":"precondition_failed"}`                  | A stale `If-Match`.                                                                                                                                                                   |
| 413    | `{"error":"too_large"}`                            | A config document over 65536 bytes.                                                                                                                                                   |
| 429    | `{"error":"rate limited"}`                         | A webhook write or ping over its limit, or a user erasure over 30 calls a minute. Carries `Retry-After`.                                                                              |
| 500    | `{"error":"internal error"}`                       | Any failure on our side.                                                                                                                                                              |
| 503    | `{"error":"credential status unavailable"}`        | The server could not read whether the token’s key is still active, so it refused the call rather than guess. Any authenticated endpoint can answer it. Carries `Retry-After`.         |
| 503    | `{"error":"unavailable, retry"}`                   | The webhook service is briefly busy or unreachable, or another user erasure is running in the project. Carries `Retry-After`, usually `1`.                                            |

## Error tokens by endpoint

### Authentication: every endpoint

| Status | `error`                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------- |
| 401    | `missing bearer token`                                                                             |
| 401    | `invalid session token`                                                                            |
| 401    | `unknown project key` (`POST /v1/token` only)                                                      |
| 400    | `malformed project key` (`POST /v1/token` only)                                                    |
| 503    | `credential status unavailable` (every endpoint that takes a session token; carries `Retry-After`) |

### Permissions: every server endpoint

`POST /v1/ingest` accepts an SDK session, so it never answers `server credentials required`.

| Status | `error`                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| 403    | `insufficient scope`                                                                            |
| 403    | `server credentials required`                                                                   |
| 403    | `the location log is readable by server integrator credentials only` (`GET /v1/locations` only) |
| 403    | `the event log is readable by server integrator credentials only` (`GET /v1/events` only)       |

### Routing: every path under `/v1`

| Status | `error`                                                                  |
| ------ | ------------------------------------------------------------------------ |
| 404    | `not found` (a path no endpoint serves)                                  |
| 405    | `method_not_allowed` (a method the path does not serve; carries `Allow`) |

### Paging: every list

| Status | `error`                                                                                                                                                                   |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `limit must be an integer in [1, 500]`                                                                                                                                    |
| 400    | `invalid_cursor`                                                                                                                                                          |
| 400    | `cursor_query_mismatch` (lists with filters: devices, locations, trips; a trip’s points, for another trip’s cursor; and users and webhooks, for another project’s cursor) |
| 410    | `expired_cursor` (locations, events)                                                                                                                                      |

### Per endpoint

| Endpoint                                                | Status | `error`                                                                                                                                                                                                                                                         |
| ------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/project`                                       | 404    | `not found` (the project is no longer hosted on this region)                                                                                                                                                                                                    |
| `GET /v1/devices/{install_id}`                          | 404    | `not found`                                                                                                                                                                                                                                                     |
| `GET /v1/devices`                                       | 400    | `invalid_user_id` (the `user_id` filter), `cursor_query_mismatch`                                                                                                                                                                                               |
| `POST /v1/devices/{install_id}/commands`                | 400    | `invalid_body` (a body over 16 KiB included), `invalid_type`, `invalid_params`, `invalid_ttl_seconds`                                                                                                                                                           |
|                                                         | 404    | `not found`                                                                                                                                                                                                                                                     |
|                                                         | 409    | `too_many_active_commands`                                                                                                                                                                                                                                      |
| `GET /v1/users`, `GET /v1/users/{user_id}`, `…/devices` | 400    | `invalid_user_id` (a path or filter id that is not 1–256 bytes of UTF-8 without control characters)                                                                                                                                                             |
|                                                         | 404    | `not found` (an id that is not a user of this project)                                                                                                                                                                                                          |
| `DELETE /v1/users/{user_id}`                            | 400    | `invalid_user_id`                                                                                                                                                                                                                                               |
|                                                         | 429    | `rate limited` (over 30 calls a minute per key)                                                                                                                                                                                                                 |
|                                                         | 503    | `unavailable, retry` (another erasure is running in the project)                                                                                                                                                                                                |
| `GET /v1/locations`                                     | 400    | `invalid_window`, `window_too_large`, `invalid_install_id`, `invalid_user_id`, `invalid_gate_reason`, `invalid_mode`, `invalid_order`, `invalid_include_gated`, `conflicting_filters`                                                                           |
| `GET /v1/trips`                                         | 400    | `invalid_install_id`, `invalid_window`                                                                                                                                                                                                                          |
| `GET /v1/trips/{trip_id}`, `…/points`                   | 404    | `not found`                                                                                                                                                                                                                                                     |
| `POST /v1/geofences`, `PUT /v1/geofences/{fence_id}`    | 400    | `invalid_body`, `invalid_name`, `invalid_geometry`, `invalid_notification`, and the geometry reasons `shape_unknown`, `coordinate_out_of_range`, `radius_not_positive`, `ring_too_few_vertices`, `self_intersection`, `hole_outside_shell`, `antimeridian_span` |
|                                                         | 404    | `not found` (`PUT` only)                                                                                                                                                                                                                                        |
|                                                         | 409    | `quota_fences` (`POST` only), `quota_vertices` (checked before the self-intersection and hole reasons), `quota_area`                                                                                                                                            |
| `GET` / `DELETE /v1/geofences/{fence_id}`               | 404    | `not found`                                                                                                                                                                                                                                                     |
| `PUT /v1/config/document`                               | 400    | `invalid_body`, `invalid_if_match`, `invalid_config: <paths>`                                                                                                                                                                                                   |
|                                                         | 412    | `precondition_failed`                                                                                                                                                                                                                                           |
|                                                         | 413    | `too_large`                                                                                                                                                                                                                                                     |
| `POST /v1/webhooks`, `PATCH /v1/webhooks/{webhook_id}`  | 400    | `invalid_body`, `invalid_endpoint_url`, `invalid_event_types`, `invalid_status` (`PATCH` only)                                                                                                                                                                  |
|                                                         | 409    | `webhook_limit_reached` (`POST` only)                                                                                                                                                                                                                           |
| `POST …/rotate-secret`, `POST …/ping`                   | 400    | `invalid_body` (a malformed body, or any body on `ping`)                                                                                                                                                                                                        |
| every `/v1/webhooks` endpoint                           | 404    | `not found` (endpoints with an id)                                                                                                                                                                                                                              |
|                                                         | 429    | `rate limited` (writes and ping)                                                                                                                                                                                                                                |
|                                                         | 503    | `unavailable, retry`                                                                                                                                                                                                                                            |

Each endpoint’s page explains when each token is returned.
