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.