Skip to content

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.

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

Every error is a JSON object with one member:

{"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 applies: an unknown id behind a valid path is still 401 first when the token is missing.

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 error, such as invalid batch.
StatusMeaningWhat to do
400The request is invalid. The token names the parameter or rule.Fix the request. Do not retry it unchanged.
401No session, or the session token is expired or invalid.Mint a new token and retry once. See Authentication.
403The session is not allowed here: wrong key kind, or a missing scope.Use a key with the right scope. Retrying will not help.
404not 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.
405method_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.
409A conflict the endpoint defines, such as a quota.Resolve the conflict (delete something, wait for commands to expire).
410expired_cursor: the data your cursor pointed into has been deleted under your plan’s retention.Restart the walk. See Pagination.
412precondition_failed: your If-Match names a revision that is no longer current.Re-read, re-apply your change, write again. See Remote config.
413too_large: the request body is over the endpoint’s cap.Send a smaller body.
429Rate limited. A Retry-After header (in seconds) is present.Wait at least Retry-After, then retry the same request. See Rate limits.
500internal error: a failure on our side, including a region we could not reach.Retry with exponential backoff, keeping your cursor.
503The 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.

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

StatusBodyWhen
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.
Statuserror
401missing bearer token
401invalid session token
401unknown project key (POST /v1/token only)
400malformed project key (POST /v1/token only)
503credential status unavailable (every endpoint that takes a session token; carries Retry-After)

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

Statuserror
403insufficient scope
403server credentials required
403the location log is readable by server integrator credentials only (GET /v1/locations only)
403the event log is readable by server integrator credentials only (GET /v1/events only)
Statuserror
404not found (a path no endpoint serves)
405method_not_allowed (a method the path does not serve; carries Allow)
Statuserror
400limit must be an integer in [1, 500]
400invalid_cursor
400cursor_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)
410expired_cursor (locations, events)
EndpointStatuserror
GET /v1/project404not found (the project is no longer hosted on this region)
GET /v1/devices/{install_id}404not found
GET /v1/devices400invalid_user_id (the user_id filter), cursor_query_mismatch
POST /v1/devices/{install_id}/commands400invalid_body (a body over 16 KiB included), invalid_type, invalid_params, invalid_ttl_seconds
404not found
409too_many_active_commands
GET /v1/users, GET /v1/users/{user_id}, …/devices400invalid_user_id (a path or filter id that is not 1–256 bytes of UTF-8 without control characters)
404not found (an id that is not a user of this project)
DELETE /v1/users/{user_id}400invalid_user_id
429rate limited (over 30 calls a minute per key)
503unavailable, retry (another erasure is running in the project)
GET /v1/locations400invalid_window, window_too_large, invalid_install_id, invalid_user_id, invalid_gate_reason, invalid_mode, invalid_order, invalid_include_gated, conflicting_filters
GET /v1/trips400invalid_install_id, invalid_window
GET /v1/trips/{trip_id}, …/points404not found
POST /v1/geofences, PUT /v1/geofences/{fence_id}400invalid_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
404not found (PUT only)
409quota_fences (POST only), quota_vertices (checked before the self-intersection and hole reasons), quota_area
GET / DELETE /v1/geofences/{fence_id}404not found
PUT /v1/config/document400invalid_body, invalid_if_match, invalid_config: <paths>
412precondition_failed
413too_large
POST /v1/webhooks, PATCH /v1/webhooks/{webhook_id}400invalid_body, invalid_endpoint_url, invalid_event_types, invalid_status (PATCH only)
409webhook_limit_reached (POST only)
POST …/rotate-secret, POST …/ping400invalid_body (a malformed body, or any body on ping)
every /v1/webhooks endpoint404not found (endpoints with an id)
429rate limited (writes and ping)
503unavailable, retry

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