> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Standardised error response model, HTTP status codes, example responses, and retry guidance for the Telemax External API.

## Error response shape

Every error response from the Telemax API returns the same JSON structure:

```json theme={null}
{
  "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"
}
```

| Field         | Type   | Description                                                                                                     |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `type`        | string | Error category: `AUTHENTICATION`, `AUTHORIZATION`, `RESOURCE`, `VALIDATION_ERROR`, `RATE_LIMIT`, `SERVER_ERROR` |
| `code`        | string | Machine-readable code identifying the specific error                                                            |
| `description` | string | Human-readable explanation and resolution hint                                                                  |
| `requestId`   | string | Unique ID for this request — include it when contacting support                                                 |
| `docUrl`      | string | Link to the specific error documentation                                                                        |

<Note>
  `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.
</Note>

***

## 401 Unauthorized

**Cause:** Request is missing authentication credentials (no JWT) or the token is invalid/expired.

**Common codes:**

| `code`                | Meaning                             |
| --------------------- | ----------------------------------- |
| `INVALID_CREDENTIALS` | Missing/invalid/expired credentials |

**Example response:**

```json theme={null}
{
  "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 /v2/api/authentication/token/user`](/v2/api-reference/post-authentication-token-user) or [`POST /v2/api/authentication/token/api-key`](/v2/api-reference/post-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's `Actions` 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:**

| `code`          | Meaning                                                               |
| --------------- | --------------------------------------------------------------------- |
| `INVALID_SCOPE` | The API key does not have the required action to access this endpoint |

**Example response:**

```json theme={null}
{
  "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 the `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 with `code: PATH_NOT_FOUND`.

**Common codes:**

| `code`           | Meaning                                                    |
| ---------------- | ---------------------------------------------------------- |
| `NOT_FOUND`      | The requested entity does not exist (or is not accessible) |
| `PATH_NOT_FOUND` | The requested URL does not match any V2 endpoint           |

**Example response:**

```json theme={null}
{
  "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 /v2/api/vehicles/list`](/v2/api-reference/post-vehicles-list) or [`GET /v2/api/vehicles/{imei}/device-ids`](/v2/api-reference/get-vehicles-imei-device-ids).

***

## 422 Unprocessable Entity

**Cause:** A route, query, or request body value is present but fails validation.

**Common codes:**

| `code`          | Meaning                                       |
| --------------- | --------------------------------------------- |
| `INVALID_INPUT` | The request parameters/body failed validation |

**Example response:**

```json theme={null}
{
  "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 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](/v2/request-response#rate-limiting).

**Example response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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                                                         |
| ------- | -------------------------------------------------------------------- |
| **Yes** | 429 (after `Retry-After`), 500 (transient), 503 (gateway timeout)    |
| **No**  | 401 (fix token), 403 (fix scope), 404 (fix ID), 422 (fix parameters) |