Skip to content
TLGPSDocumentation

Developer documentation

Developer documentation

Errors & conventions

Interpret REST responses and Gateway errors.

Handle authentication, authorization, validation and connection failures separately. Error examples are synthetic; exact human-readable messages can vary.

REST responses

Status Meaning
200 Successful read
401 Authentication is missing or invalid
403 A Company capability, permission or token ability does not allow the operation
404 Resource is missing or unavailable in the current visibility scope
409 History is unavailable because the vehicle has no assigned device or the assigned device lacks tracking configuration
422 Request validation failed: invalid history dates/pagination or connection, movement or ignition filter values
500 An unexpected server failure
{
    "message": "The given data was invalid.",
    "errors": { "from": ["The from field is required."] }
}

Collection reads include data, links and meta. Single-resource reads wrap the resource in data. Use returned pagination links and metadata rather than assuming fixed counts.

History prerequisite conflicts use the normal message envelope and do not return an empty history collection. A valid configured device with no records returns 200 and data: []. Provider/internal failures remain 500. Authorization and visibility checks still precede device-prerequisite checks; inaccessible resources do not reveal device state.

Invalid connection, movement and ignition filters, including array-shaped values, return 422 with the affected field in errors. Missing/empty optional filters are ignored. Supported movement values include no_gps.

Gateway errors

Gateway sends machine-readable codes in data.error:

{
    "type": "error",
    "timestamp": "2026-10-18T12:00:00+00:00",
    "data": {
        "error": "invalid_payload",
        "message": "Missing token."
    }
}

Common codes include authentication_failed, unauthorized, forbidden, invalid_json, invalid_payload, unknown_message, invalid_subscription and internal_error. A failed vehicle subscription batch registers none of that batch. An error is not always a disconnect: handle a subsequent connection_closed message or socket closure independently.

Rate and size limits

The current REST route configuration does not define a fixed request-rate allowance. Gateway applies bounded message sizes, subscription counts and message-rate limits; deployment settings may differ. Confirm limits for your environment rather than assuming an unlimited allowance or a published SLA.

Time and compatibility

Parse ISO-8601 timestamps with their offsets. REST V1 state timestamps retain application-timezone offsets at second precision; Gateway V1 state timestamps retain UTC with six fractional digits and Z. Both preserve nulls and the same underlying state semantics; account for the available precision when comparing instants. Gateway message-envelope timestamps are send times, not GPS measurement times. Shared address fields come from the available snapshot; Gateway retains three extra geocoder reference fields (place_id, osm_type, osm_id) for compatibility. Serialization does not trigger reverse geocoding. Optional telemetry values may be null or unavailable. Ignore unknown response fields and server message types; do not depend on JSON property order. Only the Gateway vehicle topic is supported.

Reconnecting

After disconnection, establish a new connection, authenticate and recreate permitted subscriptions. Initial state is conditional on availability. There is no advertised replay, guaranteed delivery or guaranteed latency contract; arrange recovery behavior appropriate to your integration.

Public documentation · authorized integration access required

Engineering-maintained documentation. Examples use synthetic data and placeholder credentials.

Back to top