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: Request is missing authentication credentials (no JWT) or the token is invalid/expired. Common codes:
Example response:
POST /v2/api/authentication/token/user or POST /v2/api/authentication/token/api-key. Tokens expire after approximately 24 hours (expires_in: 86399).
403 Forbidden
Cause: The API key does not have the required action permissions to access this endpoint. HTTP 403 is returned only when the key’sActions claim lacks the permission needed — not when the caller attempts to access an entity they don’t own. Accessing a non-existent entity or one that belongs to a different company returns HTTP 404 instead.
Common codes:
Example response:
Actions claim on your API key in the Telemax dashboard (API Keys V2). The key must include the action required by this endpoint. If the entity simply doesn’t exist or isn’t in your company, expect a 404 instead.
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. If the URL path itself does not match any V2 route, the API returns a 404 withcode: PATH_NOT_FOUND.
Common codes:
Example response:
POST /v2/api/vehicles/list or GET /v2/api/vehicles/{imei}/device-ids.
422 Unprocessable Entity
Cause: A route, query, or request body value is present but fails validation. Common codes:
Example response:
2025-05-01T00:00:00Z). All ID parameters must be positive integers.
429 Too Many Requests
Cause: The caller has exceeded the rate limit for a V2 endpoint. Rate limits are enforced across multiple sliding windows — per second, per minute, per hour, and per day. For the full per-endpoint limits and response headers see Rate limiting. Example response:Retry-After response header and wait that many seconds before retrying. Use exponential backoff on repeated 429s — double the wait interval on each subsequent failure 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.