Skip to main content

​
Error response shape

Every error response from the Telemax API returns the same JSON structure: 
{
  "type": "AUTHENTICATION",
  "code": "INVALID_CREDENTIALS",
  "description": "The provided API key is invalid or does not exist.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-credentials"
}
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: Request is missing authentication credentials (no JWT) or the token is invalid/expired. Common codes:
codeMeaning
INVALID_CREDENTIALSMissing/invalid/expired credentials
Example response: 
{
  "type": "AUTHENTICATION",
  "code": "INVALID_CREDENTIALS",
  "description": "The provided API key is invalid or does not exist.",
  "requestId": "0HNLTALNU4DCO:00000004",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-credentials"
}
Resolution: Request a new token via POST /api/v2/authentication/token/user or POST /api/v2/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
INVALID_SCOPEThe token does not grant permission to access this resource
Example response: 
{
  "type": "AUTHORIZATION",
  "code": "INVALID_SCOPE",
  "description": "The provided token does not have permission to access this resource.",
  "requestId": "0HNLTALNU4DCE:00000002",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-scope"
}
Resolution: Check your company ID against the list returned by GET /api/v2/companies. 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. If the URL path itself does not match any V2 route, the API returns a 404 with code: PATH_NOT_FOUND. Common codes:
codeMeaning
NOT_FOUNDThe requested entity does not exist (or is not accessible)
PATH_NOT_FOUNDThe requested URL does not match any V2 endpoint
Example response: 
{
  "type": "RESOURCE",
  "code": "NOT_FOUND",
  "description": "Vehicle 9999 was not found.",
  "requestId": "0HNLTALNU4DDM:00000003",
  "docUrl": "https://docs.telemax.com.au/errors/not-found"
}
Resolution: Verify the ID using POST /api/v2/vehicles/list or GET /api/v2/vehicles/{imei}/device-ids.

​
422 Unprocessable Entity

Cause: A route, query, or request body value is present but fails validation. Common codes:
codeMeaning
INVALID_INPUTThe request parameters/body failed validation
Example response: 
{
  "type": "VALIDATION_ERROR",
  "code": "INVALID_INPUT",
  "description": "One or more route or query parameters could not be parsed.",
  "requestId": "0HNLTALNU4DDJ:00000004",
  "docUrl": "https://docs.telemax.com.au/errors/invalid-input"
}
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

Cause: The caller has exceeded the rate limit for a V2 endpoint. Rate limits are applied per token using a 60-second sliding window. For the full per-endpoint limits and response headers see Rate limits. Example response: 
{
  "type": "RATE_LIMIT",
  "code": "RATE_LIMIT_EXCEEDED",
  "description": "Too many requests. Please slow down.",
  "requestId": "0HNLTALNU4DD8:00000006",
  "docUrl": "https://docs.telemax.com.au/errors/rate-limit-exceeded"
}
Resolution: Read the 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: 
{
  "type": "SERVER_ERROR",
  "code": "INTERNAL_SERVER_ERROR",
  "description": "An unexpected error occurred. Please try again later.",
  "requestId": "0HNLTALNU4DE1:00000002",
  "docUrl": "https://docs.telemax.com.au/errors/internal-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)