Developer API
Developer APIAPI ReferenceErrors

Error Handling

How to interpret and handle API errors

Error Response Format

All errors are returned as JSON with a consistent format. Every error response includes a machine-readable code and a human-readable message.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist"
  }
}

Branch on error.code, not on the message text—messages may change, codes are stable. Some errors add a details object with machine-readable detail, such as the reason a geofence shape was refused. Ignore keys you do not recognize.

HTTP Status Codes

200 OK

Request succeeded and returned data.

201 Created

A resource was created (for example, a new webhook subscription).

400 Bad Request

Invalid request parameters, missing required fields, or malformed JSON.

401 Unauthorized

Missing or invalid API key.

403 Forbidden

Valid key, but it lacks the required scope—or the API is not enabled for this workspace.

404 Not Found

Resource does not exist or is not visible to your key.

405 Method Not Allowed

The HTTP method is not supported for this path.

409 Conflict

A workspace limit was reached (for example, the maximum number of integrations), an Idempotency-Key was reused or is still in flight, or the request conflicts with what is stored. The code says which.

413 Content Too Large

A bulk geofence create is too large to save in one request. Nothing was created.

415 Unsupported Media Type

Request bodies must be sent as application/json.

422 Unprocessable Content

The request is valid but would read too much at once, for example a geofence visits window that holds too many recorded locations.

429 Too Many Requests

Rate limit exceeded. Retry after the time given in the Retry-After header.

500 Internal Server Error

Unexpected server error. Retry with exponential backoff.

503 Service Unavailable

The request could not be handled for a moment. Retry after the time given in the Retry-After header. A geofence write may have landed: retry a geofence create with the same Idempotency-Key, which never writes it twice, or list geofences before retrying one sent without a key.

Error Codes

The code field is always one of the following values.

Authentication & access

unauthorized (401)

The API key is missing or invalid. Check the key and how you send it.

forbidden (403)

The key is valid but lacks the scope this endpoint requires. The message names the missing scope; create a new key with that scope from Settings → API Keys.

api_disabled (403)

API access is not enabled for this workspace. Create an API key from Settings → API Keys to enable it automatically. The same code is returned while the workspace has no active plan (a cancelled subscription or a failed payment): update the payment method or resume the subscription to use the API again.

feature_not_enabled (403)

The workspace does not have the feature this endpoint reads, for example the geofence time report behind GET /v1/geofences/{geofenceId}/visits.

Resource & method

not_found (404)

The requested resource does not exist or is not visible to your key. Verify the resource ID (e.g., tagId, webhookId).

method_not_allowed (405)

The HTTP method is not supported for this path.

unsupported_media_type (415)

Send request bodies as application/json.

Validation (400)

invalid_body

The request body is missing or malformed.

invalid_request

The request is well-formed but asks for something the endpoint does not accept, for example a bulk create without 1 to 450 geofences, a geofence create body with ownerId, userId or workspaceOwnerUid (the workspace always comes from the API key), or a visits request whose tagIds is empty, malformed or over 100 ids.

invalid_url

The webhook url is missing or is not a valid HTTPS URL.

invalid_events

The events value is not an array, is empty, or contains an unknown event type. Omitting events entirely is allowed—it subscribes to every event type except security.event, which must be named.

invalid_label

The label is invalid.

invalid_active

The active flag must be a boolean.

invalid_range

The start or end timestamp is invalid, or start is after end. For geofence visits, from must be before to and in the past, and the window can span at most 400 days. (Note: an out-of-range limit is clamped to the allowed maximum, and an unrecognized order defaults to asc — neither raises an error.)

invalid_cursor

A cursor is not a nextCursor from that endpoint (geofence visits or security events). On geofence visits it is also returned for a cursor sent with another geofence, window or tagIds, or a key with another tag scope, than the page that returned it. Send it with the same values; if you left the window out, use the from and to the first page returned.

invalid_geofence

A geofence field is missing or out of range — for example the name, the center latitude/longitude, radiusMeters, a polygon's vertices, a corridor's path or widthMeters, or an alerts setting. On an update it is also returned for a shape edit without type that does not fit the current shape (for example center on a polygon or corridor, or vertices on a circle), path or widthMeters alone, fields of two shapes without type, or a field of another shape beside type (for example path with type: "polygon"). Sending both alerts.emailAddress and alerts.emailAddresses is also invalid_geofence. The message names the problem; in a bulk create it starts with geofences[<index>]: and details.item is that index.

A shape error carries details.reason and, when one point is at fault, its 0-based details.index in vertices or path:

  • invalid_type: the type is not circle, polygon or corridor, or a create without type sends vertices or path.
  • invalid_coordinates: a point is missing or out of range (latitude -90 to 90 for a circle center, -85 to 85 for polygon and corridor points; longitude -180 to 180).
  • invalid_radius: radiusMeters is not a number from 10 to 100,000 (text such as "300" is refused).
  • invalid_width: widthMeters is not a number from 500 to 20,000.
  • too_few_points / too_many_points: a polygon needs 3 to 500 corners, a corridor 2 to 1,000 points.
  • duplicate_point: a point is less than 1 m from the one before it.
  • self_intersecting: the polygon's outline crosses itself.
  • too_small: the polygon is under 100 square meters or too thin to hold a 10 m circle, or the route is shorter than 50 m.
  • too_large: the polygon spans more than 2,000 km, or the route is longer than 10,000 km or covers more than half the globe east to west.

invalid_target_tags

A geofence's targetTagIds is not a valid array of known tag ids (or the literal "all"), is empty, or exceeds the per-geofence target limit. (Requesting "all" with a key that lacks all-tags scope returns forbidden instead.)

invalid_expiry

A share link's expiry is invalid: provide either expiresInSeconds or expiresAt (not both), at least 60 seconds in the future and within the maximum share-link lifetime.

invalid_tag_update (400)

A PATCH /v1/tags/{tagId} body is invalid: an unsupported field, a pause setting that is not an object, a paused that is not a boolean, or an until that is not a future timestamp (ISO-8601 or epoch milliseconds) or null. The message names the field.

invalid_customer_page (400)

A Customer Page body is invalid: an unsupported field or feature, a feature that is not a boolean, an expiresAt that is not a future timestamp or null, or an update with no fields. The message names the problem.

invalid_branding (400)

A Customer Page branding update is invalid: an unsupported field, no fields at all, or a value the branding refuses. The message names the problem.

invalid_idempotency_key (400)

The Idempotency-Key header is not 1 to 255 printable ASCII characters.

invalid_since (400)

The since query value on GET /v1/security-events is not an ISO-8601 timestamp or epoch milliseconds.

Conflict, limits & rate

limit_exceeded (409)

A workspace limit was reached (for example, the maximum number of integrations). For geofences only the ones a create adds count, so a retry with the same Idempotency-Key does not count its own geofences again.

conflict (409)

The request conflicts with what is stored. On a geofence create or bulk create, the Idempotency-Key already created a geofence that differs from this request: it was edited since, or the key came back with a different body after its 24-hour record expired. On a webhook create, the webhook the Idempotency-Key created has since been updated, had its secret rotated or been deleted, or the key is more than 24 hours old and its webhook still exists. Nothing was written. Send a new key with each new request.

idempotency_key_reused (409)

This Idempotency-Key was already used with a different request body in the last 24 hours. Send a new key with each new request.

tag_not_shareable (409)

A share link cannot be created because the tag is not yet linked to hardware or is deactivated. Link (or reactivate) the tag, then retry.

activation_blocked (400 or 409)

A tag cannot be activated or deactivated as asked. 409: the workspace has no free seat, the tag is still waiting for its hardware, or a payment dispute is open on the account; 400: the request itself was refused. The message says why.

customer_page_tag_not_shareable (409)

A Customer Page names a tag that is not yet linked to hardware or is deactivated. Link (or reactivate) the tag, or leave it out.

customer_page_conflict (400 or 409)

A Customer Page create or update was refused when it was saved: 400 for a page the service cannot accept as sent, 409 for a page revoked while the update was in flight. The message says why.

customer_page_revoked (409)

The Customer Page has been revoked: it can no longer be changed and its token cannot be rotated. Create a new page instead.

payload_too_large (413)

A bulk create's geofences together take more than 4 MiB as JSON, and nothing was created. Send fewer geofences per request, or fewer corners, route points, target tags or recipients per geofence.

window_too_large (422)

A page of geofence visits covers too many recorded locations for the tags on it. Choose a shorter window or a smaller limit.

tag_filter_scope_too_large (422)

A GET /v1/tags request with search or label reaches more than 1,000 visible tags. Use a key with a narrower tag scope, or list without filters and filter the pages yourself.

rate_limited (429)

The per-key rate limit was exceeded. Honor the Retry-After header and back off.

too_many_requests (429)

Too many unauthenticated requests from your IP. Slow down and retry after the indicated delay.

Server

internal (500)

An unexpected server error occurred on our side. Safe to retry with exponential backoff.

service_unavailable (503)

The service behind this request did not answer, or a workspace's history is still being prepared for geofence visits. A write may have landed. Retry after the Retry-After delay (30 seconds). Retrying a geofence create with the same Idempotency-Key and body is safe: it returns the same geofences and never writes them twice. Without a key, list geofences before retrying a create.

Rate Limiting

Each response includes rate-limit information in its headers:

X-RateLimit-Limit: Maximum requests allowed in the current window for your API key.

X-RateLimit-Remaining: Requests remaining in the current window.

X-RateLimit-Reset: Unix timestamp (seconds) when the window resets.

When you exceed the limit, you receive a 429 response with a Retry-After header. Wait that many seconds before retrying. See Usage & Rate Limits for the concrete limits.

Best Practices

  • Always check HTTP status codes. Don't assume a 200 response; handle 4xx and 5xx codes.
  • Branch on the error code. Log error.code and message—frequent forbidden errors, for example, mean your key needs more scopes.
  • Implement exponential backoff. For 429 and 5xx errors, wait before retrying. Start with a small delay (e.g., 1 second) and increase it with each retry.
  • Don't retry 4xx errors (except 429). A 400 or 401 won't succeed on retry—fix the request first.
  • Handle 404 gracefully. A missing tag might have been deactivated. Skip it or warn the user.
  • Monitor rate limits. If you frequently hit the limit, optimize your polling strategy—poll the fleet delta endpoint instead of per-tag requests, and widen your interval. See the polling guide for patterns that stay well under the limit.

Example Error Handling

// Example: handle common errors
const response = await fetch('https://api.taglogger.com/v1/tags', {
  headers: { 'Authorization': 'Bearer tl_live_xxx' }
});

if (response.status === 401) {
  // Invalid or missing API key
  const error = await response.json();
  console.error('Auth error:', error.error.code);
} else if (response.status === 429) {
  // Rate limited - wait before retrying
  const retryAfter = Number(response.headers.get('Retry-After')) || 1;
  console.warn('Rate limited. Retry after ' + retryAfter + 's');
  await new Promise(r => setTimeout(r, retryAfter * 1000));
} else if (response.status >= 500) {
  // Server error - retry with backoff
  console.error('Server error. Retrying...');
} else if (response.ok) {
  const data = await response.json();
  console.log('Success:', data);
}