> ## 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.

# Engine codes

> Enriched engine/diagnostic codes for a vehicle with full AI analysis, severity, and detection location.

### Overview

Returns engine code (OBD-II / Diagnostic Trouble Code) records from the most recent engine fault event for a vehicle. Each code is enriched with AI-generated analysis including a plain-English explanation of why it matters, a list of possible root causes, and step-by-step recommended actions — written as full descriptive sentences, not short labels.

<Note>The V1 version of this endpoint is [DTC codes](/v1/api-reference/get-devices-dtc-codes). V2 is paginated, significantly enriched with AI analysis, and the path has changed from `/dtc` to `/engine-codes`.</Note>

<Note>**Rate limit:** 10 req/s · 30/min · 6,000/hr · 144,000/day</Note>

### Endpoint

`GET /v2/api/vehicles/{id}/engine-codes`

### Path parameters

<ParamField path="id" type="integer" required>
  Vehicle ID.
</ParamField>

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="pageSize" type="integer" default="50">
  Records per page.
</ParamField>

### Response

**200 OK** — `PagedListResult<EngineCodeDto>`

| Field               | Type             | Description                                                                              |
| ------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| code                | string           | Raw OBD-II code (e.g. `P0420`)                                                           |
| description         | string           | Standard code description (e.g. `"Catalyst System Efficiency Below Threshold (Bank 1)"`) |
| whyThisMatters      | string\[]        | AI-generated full sentences explaining the impact on vehicle operation and safety        |
| possibleCauses      | string\[]        | AI-generated full sentences describing the most likely root causes                       |
| recommendedActions  | string\[]        | AI-generated full sentences with step-by-step recommended actions                        |
| severity            | string \| null   | Urgency level: `"High"`, `"Medium"`, or `"Low"`. May be null for older cached records    |
| detectedAt          | datetime \| null | When the fault was detected (user's local timezone)                                      |
| detectedAtFormatted | string           | Human-readable formatted timestamp                                                       |
| location.address    | string \| null   | Street address where the fault was detected; null if geocoding failed                    |
| location.latitude   | number \| null   | Latitude of detection location                                                           |
| location.longitude  | number \| null   | Longitude of detection location                                                          |

<Note>When a vehicle has no engine codes, the API returns `items: null` (not `[]`) and `currentPage: 0` (not `1`). Always null-check `items` before iterating.</Note>

### Example response

```json theme={null}
{
  "items": [
    {
      "code": "P0420",
      "description": "Catalyst System Efficiency Below Threshold (Bank 1)",
      "whyThisMatters": [
        "This fault indicates your catalytic converter is no longer processing exhaust gases effectively, which means your vehicle is producing higher levels of harmful emissions than permitted.",
        "If left unaddressed, the engine management system may enter a reduced-power mode, leading to noticeably worse fuel economy and throttle response.",
        "In some regions this fault will cause the vehicle to fail an emissions inspection."
      ],
      "possibleCauses": [
        "The catalytic converter itself has degraded or been poisoned — commonly caused by using leaded fuel, coolant leaks into the exhaust, or high-mileage wear.",
        "A faulty upstream or downstream oxygen sensor is reporting incorrect readings, making a healthy converter appear to be failing.",
        "An exhaust leak upstream of the converter is allowing unmetered air to enter, skewing the sensor readings."
      ],
      "recommendedActions": [
        "Begin by scanning for any additional fault codes, particularly oxygen sensor faults (P0130–P0167), as these should be resolved first before condemning the catalytic converter.",
        "Inspect the exhaust system for any leaks between the engine and the catalytic converter, and repair any found.",
        "If the oxygen sensors test within spec and there are no exhaust leaks, have the catalytic converter tested for flow restriction and converter efficiency under load — replacement is likely required."
      ],
      "severity": "Medium",
      "detectedAt": "2026-04-27T14:30:00",
      "detectedAtFormatted": "27 Apr 2026 2:30 PM",
      "location": {
        "address": "42 George St, Sydney NSW 2000",
        "latitude": -33.8688,
        "longitude": 151.2093
      }
    }
  ],
  "currentPage": 1,
  "numberOfPages": 1,
  "totalResults": 1,
  "lastResultIndex": 0
}
```

### Error responses

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| 401    | Token does not have access to this vehicle |
| 404    | Vehicle not found                          |

```bash theme={null}
curl "https://api.telemax.com.au/v2/api/vehicles/88421/engine-codes" \
  -H "Authorization: Bearer <token>"
```


## OpenAPI

````yaml openapi.yaml GET /v2/api/vehicles/{id}/engine-codes
openapi: 3.1.0
info:
  title: Telemax External API (V2)
  version: '2026-04-14'
  description: >
    Telemax External API — fleet telemetry, vehicle commands, and integrations.


    **Base URL:** `https://api.telemax.com.au`


    **Authentication:** All routes require a `Bearer` JWT unless marked
    `[AllowAnonymous]`.

    Obtain tokens via `POST /v2/api/authentication/token/api-key`.


    **RESTful architecture:** V2 uses standard HTTP methods (GET, POST, PUT,
    DELETE) with

    resource-based routes and consistent pagination via `page` and `pageSize`
    query parameters.


    **API versioning:** All responses will include an `X-API-Version` header
    containing the

    date-based version string (e.g. `2026-04-28`). See the
    [Changelog](/v2/changelog) for

    the deprecation policy and version history.


    For full documentation including error handling, pagination, and known field
    quirks, see [docs.telemax.com.au](https://docs.telemax.com.au).
servers:
  - url: https://api.telemax.com.au
security:
  - BearerAuth: []
paths:
  /v2/api/vehicles/{id}/engine-codes:
    get:
      summary: Engine codes (V2)
      description: >-
        Enriched engine/diagnostic codes with full AI-generated analysis and
        detection location.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          example: 88421
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                items:
                  - code: P0420
                    description: Catalyst System Efficiency Below Threshold (Bank 1)
                    whyThisMatters:
                      - >-
                        This fault indicates your catalytic converter is no
                        longer processing exhaust gases effectively, which means
                        your vehicle is producing higher levels of harmful
                        emissions than permitted.
                      - >-
                        If left unaddressed, the engine management system may
                        enter a reduced-power mode, leading to noticeably worse
                        fuel economy and throttle response.
                      - >-
                        In some regions this fault will cause the vehicle to
                        fail an emissions inspection.
                    possibleCauses:
                      - >-
                        The catalytic converter itself has degraded or been
                        poisoned — commonly caused by using leaded fuel, coolant
                        leaks into the exhaust, or high-mileage wear.
                      - >-
                        A faulty upstream or downstream oxygen sensor is
                        reporting incorrect readings, making a healthy converter
                        appear to be failing.
                      - >-
                        An exhaust leak upstream of the converter is allowing
                        unmetered air to enter, skewing the sensor readings.
                    recommendedActions:
                      - >-
                        Begin by scanning for any additional fault codes,
                        particularly oxygen sensor faults (P0130–P0167), as
                        these should be resolved first before condemning the
                        catalytic converter.
                      - >-
                        Inspect the exhaust system for any leaks between the
                        engine and the catalytic converter, and repair any
                        found.
                      - >-
                        If the oxygen sensors test within spec and there are no
                        exhaust leaks, have the catalytic converter tested for
                        flow restriction and converter efficiency under load —
                        replacement is likely required.
                    severity: Medium
                    detectedAt: '2026-04-27T14:30:00'
                    detectedAtFormatted: 27 Apr 2026 2:30 PM
                    location:
                      address: 42 George St, Sydney NSW 2000
                      latitude: -33.8688
                      longitude: 151.2093
                totalResults: 1
                lastResultIndex: 1
                currentPage: 1
                numberOfPages: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            **404 Not Found** — The requested vehicle does not exist or is not
            accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                type: RESOURCE
                code: NOT_FOUND
                description: Vehicle was not found.
                requestId: 0HNLTALNU4DDG:00000002
                docUrl: https://docs.telemax.com.au/errors/not-found
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: >
        **401 Unauthorized** — JWT is missing, expired, or malformed.

        The JWT bearer middleware rejects the request before it reaches the
        controller.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            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
    Forbidden:
      description: >
        **403 Forbidden** — Token is valid but the caller does not have access
        to the requested company or vehicle.

        Tokens issued for one company cannot access resources scoped to a
        different company in the hierarchy.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: AUTHORIZATION
            code: INVALID_SCOPE
            description: >-
              The provided token does not have permission to access this
              resource.
            requestId: 50e5c5f7-ccae-4ab6-b070-56d6645ceb1e
            docUrl: https://docs.telemax.com.au/errors/invalid-scope
    UnprocessableEntity:
      description: >
        **422 Unprocessable Entity** — A parameter is present but has an invalid
        format (e.g. negative vehicle ID, malformed ISO 8601 date string).
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: VALIDATION_ERROR
            code: INVALID_INPUT
            description: One or more route or query parameters could not be parsed.
            requestId: req_9f3e7c1b
            docUrl: https://docs.telemax.com.au/errors/invalid-input
    TooManyRequests:
      description: >
        **429 Too Many Requests** — Rate limit exceeded. Check the Retry-After
        header for the number of seconds to wait before retrying.

        Use exponential backoff: wait Retry-After seconds, then double the
        interval on each subsequent 429.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: RATE_LIMIT
            code: RATE_LIMIT_EXCEEDED
            description: Too many requests. Please slow down.
            requestId: req_6d2f8b4a
            docUrl: https://docs.telemax.com.au/errors/rate-limit-exceeded
    InternalServerError:
      description: >
        **500 Internal Server Error** — An unexpected error occurred. Include
        the requestId when contacting support.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            type: SERVER_ERROR
            code: INTERNAL_SERVER_ERROR
            description: An unexpected error occurred. Please try again later.
            requestId: req_1e5a3c7d
            docUrl: https://docs.telemax.com.au/errors/internal-server-error
  schemas:
    ApiError:
      type: object
      description: Standard error response returned by all API endpoints.
      properties:
        type:
          type: string
          description: >-
            Error category (e.g. AUTHENTICATION, AUTHORIZATION, RESOURCE,
            VALIDATION_ERROR, RATE_LIMIT, SERVER_ERROR).
          example: AUTHENTICATION
        code:
          type: string
          description: Machine-readable error code within the category.
          example: INVALID_CREDENTIALS
        description:
          type: string
          description: Human-readable explanation of the error and how to resolve it.
          example: The provided API key is invalid or does not exist.
        requestId:
          type: string
          description: Unique request identifier for support correlation.
          example: req_7f3a2b1c
        docUrl:
          type: string
          format: uri
          description: Link to the relevant error documentation page.
          example: https://docs.telemax.com.au/errors/invalid-credentials
      required:
        - type
        - code
        - description
  headers:
    X-RateLimit-Limit:
      description: >-
        Maximum number of requests allowed per minute for this token. **Not yet
        active** — this header will be added once the rate-limit middleware is
        deployed. See the [Changelog](/v2/changelog) for the rollout date.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: >-
        Number of requests remaining in the current rate limit window. **Not yet
        active** — see `X-RateLimit-Limit`.
      schema:
        type: integer
        example: 47
    X-RateLimit-Reset:
      description: >-
        Unix timestamp (seconds) at which the current rate limit window resets.
        **Not yet active** — see `X-RateLimit-Limit`.
      schema:
        type: integer
        example: 1746000060
    Retry-After:
      description: Number of seconds to wait before retrying after a 429 response.
      schema:
        type: integer
        example: 30
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        JWT Bearer token obtained from `POST
        /v2/api/authentication/token/api-key`.


        **Lifetime:** ~24 hours (86,399 seconds). Cache the token and reuse it.
        Re-authenticate 5 minutes before expiry.


        **Scoping:** API key tokens are scoped to the company the key belongs to
        and may restrict

        access to a vehicle allowlist and/or action set (see token claims).


        **No refresh endpoint** — re-authenticate with your API key when the
        token expires.

````