Skip to main content

​
Error response shape

Errors from the Telemax API use this JSON structure (ApiError). The exceptions are listed under Other response shapes.
requestId is present in every V2 error response that uses this shape; the suspended-company 403 below has none. 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.

​
Other response shapes

​
Error codes and reference pages

The docUrl of an error links to its reference page.

​
401 Unauthorized

Cause: The bearer token is missing, invalid or expired. These responses are returned before rate limiting, so they carry no X-RateLimit-* or X-API-Version headers. The token endpoint returns the same code when the API key itself is unknown or deleted; that response does carry X-API-Version. Common codes: Example response:
Resolution: Request a new token via POST /v2/api/authentication/token/api-key. Tokens expire after approximately 24 hours (expires_in: 86399).

​
403 Forbidden

There are two causes. 1. The API key lacks the permission the endpoint requires (INVALID_SCOPE). Each API key carries a set of permitted actions, and endpoints require the matching one. A key without the endpoint’s permission gets 403; some endpoints report an ID they cannot find as 404 first. With the permission, an ID outside your companies gets 404.
Resolution: Check the permissions of your key under API Keys V2 in the Telemax dashboard. The actions of an existing key cannot be changed: create a key that includes the action this endpoint requires, then request a new token with it. 2. The company the API key belongs to is suspended or otherwise not active, or a company above it is. Every authenticated endpoint then returns 403 with a different body. It has no type, requestId or docUrl:
While the company is suspended, the token endpoint itself refuses to issue tokens:
Resolution: Contact Telemax support.

​
404 Not Found

Cause: The resource in the request does not exist, or is not in the companies your token can access. If the URL path itself does not match any V2 route, the API returns 404 with code: PATH_NOT_FOUND, without rate-limit headers. Common codes: Example response:
Resolution: Check the ID. Company IDs come from GET /v2/api/companies. A vehicle’s ID can be looked up by IMEI with GET /v2/api/vehicles/{imei}/device-ids.

​
409 Conflict

Cause: The request conflicts with the vehicle’s current odometer configuration. Common codes: Example responses:
Resolution: Do not retry unchanged. Check the vehicle’s odometer source with GET /v2/api/vehicles/{id}/odometer.

​
422 Unprocessable Entity

Cause: A route, query or request body value is missing, cannot be parsed, or fails validation. Every model-binding failure returns the same description: “One or more route or query parameters could not be parsed.” Model-binding failures include a missing required parameter, a value of the wrong type, and a body in the wrong format. Validation inside an endpoint returns its own description, for example pageSize cannot exceed 500 for this endpoint. Common codes: Example response:
Resolution:
  • Check that every required parameter is present.
  • Date-time parameters must be ISO 8601 strings (e.g. 2025-05-01T00:00:00Z).
  • ID parameters must be integers.

​
429 Too Many Requests

Cause: A rate-limit window for your API key on this endpoint is exhausted.
  • Limits are enforced in four fixed windows: per second, per minute, per hour and per day.
  • A request over a limit is rejected, not queued.
  • The response has no X-API-Version header.
  • For the per-endpoint limits and the response headers, see Rate limiting.
Example response:
Resolution:
  • Wait the number of seconds in the Retry-After header before retrying.
  • It is the length of the window that was exhausted: 1, 60, 3600 or 86400. Waiting that long always clears that window.
  • If another window is also used up, the retry gets a new 429 whose Retry-After is that window’s length; wait again.

​
500 Internal Server Error

Cause: An unexpected server-side error occurred. It appears in two forms:
  • SERVER_ERROR / INTERNAL_SERVER_ERROR, when an operation fails;
  • SERVER / INTERNAL_ERROR, for an unhandled exception.
Example responses:
Resolution: Retry after a short delay. If the error persists, contact Telemax support and include the requestId value.

​
503 Service Unavailable

Cause: The gateway in front of the API could not reach it, for example during a deployment. The application itself does not return 503, so the body is not the JSON error shape. Resolution: Retry after a short delay.

​
Retryable vs non-retryable