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.
curl -s -w '%{http_code}\n' https://api.in1.getbeekon.com/v1/project # no token# {"error":"missing bearer token"}# 401The envelope
Section titled “The envelope”Every error is a JSON object with one member:
{"error":"insufficient scope"}Content-Type: application/json.erroris 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
404with{"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) answers405with{"error":"method_not_allowed"}, and anAllowheader lists the methods the path does serve, for exampleAllow: GET, HEAD.HEADis listed whereverGETis.
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
applies: an unknown id behind a valid path is still 401 first when the token is missing.
Error string format
Section titled “Error string format”The error string has one of three shapes:
- A
snake_casetoken, such asinvalid_window,invalid_body,expired_cursororquota_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 asinvalid_config: sync.batch_size, tracking.accuracy_mode. The remote-config document only. Prefix-matchinvalid_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 errorormissing bearer token. The authentication, permission, lookup (404 not found) and server-failure answers shared by every endpoint, the paging messagelimit must be an integer in [1, 500], and every ingest error, such asinvalid batch.
Status codes
Section titled “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. |
403 | The session is not allowed here: wrong key kind, or a missing scope. | 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. |
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. |
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. |
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. |
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.
Exact bodies
Section titled “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. |
| 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
Section titled “Error tokens by endpoint”Authentication: every endpoint
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.