Skip to main content

​
Error response shape

Every error response from the Telemax API returns the same JSON structure: 
{
  "type": "AUTHENTICATION",
  "code": "TOKEN_EXPIRED",
  "description": "The access token has expired. Request a new token.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors#token-expired"
}
FieldTypeDescription
typestringError category: AUTHENTICATION, AUTHORIZATION, RESOURCE, VALIDATION_ERROR, RATE_LIMIT, SERVER_ERROR
codestringMachine-readable code identifying the specific error
descriptionstringHuman-readable explanation and resolution hint
requestIdstringUnique ID for this request — include it when contacting support
docUrlstringLink to the specific error documentation
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:
codeMeaning
TOKEN_EXPIREDToken lifetime has elapsed
TOKEN_MALFORMEDToken cannot be parsed or signature is invalid
TOKEN_MISSINGNo Authorization: Bearer ... header was sent
Example response: 
{
  "type": "AUTHENTICATION",
  "code": "TOKEN_EXPIRED",
  "description": "The access token has expired. Request a new token.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors#token-expired"
}
Resolution: Request a new token via 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:
codeMeaning
COMPANY_ACCESS_DENIEDThe company ID in the request is not in the caller’s accessible hierarchy
VEHICLE_ACCESS_DENIEDThe vehicle does not belong to any company accessible by this token
Example response: 
{
  "type": "AUTHORIZATION",
  "code": "COMPANY_ACCESS_DENIED",
  "description": "Your token does not grant access to company 99. Ensure you are using a token issued for this company.",
  "requestId": "0HNLTALNU4DCE:00000002",
  "docUrl": "https://docs.telemax.com.au/errors#company-access-denied"
}
Resolution: Check your company ID against the list returned by 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:
codeMeaning
VEHICLE_NOT_FOUNDNo vehicle with the given ID exists
COMPANY_NOT_FOUNDNo company with the given ID exists
IMEI_NOT_FOUNDNo device registered with the given IMEI
Example response: 
{
  "type": "RESOURCE",
  "code": "VEHICLE_NOT_FOUND",
  "description": "Vehicle with ID 9999 was not found.",
  "requestId": "0HNLTALNU4DDM:00000003",
  "docUrl": "https://docs.telemax.com.au/errors#not-found"
}
Resolution: Verify the ID using 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:
codeMeaning
INVALID_DATE_FORMATDate/time string is not valid ISO 8601
INVALID_IDVehicle or company ID is not a positive integer
INVALID_PARAMETEROther parameter format violation
Example response: 
{
  "type": "VALIDATION_ERROR",
  "code": "INVALID_DATE_FORMAT",
  "description": "The 'from' parameter '2025-13-45' is not a valid ISO 8601 date-time string.",
  "requestId": "0HNLTALNU4DDJ:00000004",
  "docUrl": "https://docs.telemax.com.au/errors#invalid-parameter"
}
Resolution: All date-time parameters must be ISO 8601 strings (e.g. 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.
Cause: The caller has exceeded the rate limit on a V2 endpoint. The limit is 60 requests per 60-second sliding window per token. Example response: 
{
  "type": "RATE_LIMIT",
  "code": "TOO_MANY_REQUESTS",
  "description": "Too many requests. Please try again later.",
  "requestId": "0HNLTALNU4DD8:00000006",
  "docUrl": "https://docs.telemax.com.au/errors#rate-limit"
}
Resolution: Check the 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: 
{
  "type": "SERVER_ERROR",
  "code": "INTERNAL_ERROR",
  "description": "An unexpected error occurred. Please try again or contact support with the requestId.",
  "requestId": "0HNLTALNU4DE1:00000002",
  "docUrl": "https://docs.telemax.com.au/errors#server-error"
}
Resolution: Retry after a short delay. If the error persists, contact Telemax support and include the requestId value.

​
Retryable vs non-retryable

Retry?Status codes
Yes429 (after Retry-After), 500 (transient), 503 (gateway timeout)
No401 (fix token), 403 (fix scope), 404 (fix ID), 422 (fix parameters)