Error response shape
Every error response from the Telemax API returns the same JSON structure:requestId is present in all V2 error responses. V1 error responses may omit this field.
The format is an ASP.NET Kestrel connection/request ID (e.g. "0HNLTALNU4DCO:00000004"), not a human-readable string.401 Unauthorized
Cause: JWT is missing, expired, or malformed. The request is rejected by bearer middleware before reaching the controller. Common codes:
Example response:
POST /api/authentication/token/user or POST /api/authentication/token/api-key. Tokens expire after approximately 24 hours (expires_in: 86399).
403 Forbidden
Cause: Token is valid but the caller does not have access to the requested company or vehicle. Tokens are scoped to a company hierarchy — a token issued for company A cannot access resources belonging to company B. Common codes:
Example response:
POST /api/GetCompanies. Use the correct companyId or request a token scoped to that company.
404 Not Found
Cause: The vehicle ID, company ID, or IMEI in the request does not exist or is not accessible with the current token. Common codes:
Example response:
POST /api/Devices or GET /api/GetDeviceId/{imei}.
422 Unprocessable Entity
Cause: A parameter is present but has an invalid format — for example, a date string that cannot be parsed as ISO 8601, or a negative vehicle ID. Common codes:
Example response:
2025-05-01T00:00:00Z). All ID parameters must be positive integers.
429 Too Many Requests
V1 endpoints (
/api/...) are not rate-limited. A 429 response will not occur on V1 routes. Rate limiting applies only to V2 (/api/v2/...) endpoints — if you are on V1, you can skip this section.Retry-After response header for the number of seconds to wait. Use exponential backoff: after the first 429, wait Retry-After seconds; double the interval on each subsequent 429 up to a maximum of 60 seconds.
500 Internal Server Error
Cause: An unexpected server-side error occurred. This is not caused by the request parameters. Example response:requestId value.