Errors and handling

All the HTTP response codes you can expect from Telematica APIs, and how to handle them.

This document outlines error handling for All charger endpoints, Inverter endpoints, HVAC endpoints and Battery endpoints

The general schema of errors from Telematica APIs will be as follows:

{
    'message': 'A human friendly message about the error',
    'error': 'ERROR_CODE', // Unique identifier for the error
    'statusCode': 500, // HTTP Status code,
    'action': { 'dev': "DEV_ACTION_CODE", 'user': "USER_ACTION_CODE" }, // Action required from developer's or user's end, if any
}

In general, we categorise all errors related to business logic into three categories:

  • 412 status code
    This error code indicates errors related to the connection between Telematica and your app
  • 503 status code
    This error code represents errors related to downstream OEM APIs. There is no action required from the end users' or developer's end.
  • 500 status code
    This error code represents errors that can be mitigated by the end user's intervention (Ex. charger not plugged into vehicle). The message field, in this case, contains the details of the error along with a call to action.

412 errors

ErrorDescription
NOT_FOUNDDevice entry not found
RELOGIN_REQUIREDThe user changed credentials for the OEM account or revoked access
Action RECONNECT_ACCOUNT is recommended.
DEVICE_DISCONNECTEDThe specific device has been disconnected from the OEM account.
Action PERMANENTLY_DELETE_DEVICE is recommended.
INVALID_REQUESTThe request body is invalid. Check message field for a detailed explanation.
USER_CONSENT_REQUIREDThe requested device/data point is out of scope for your app.
Action RECONNECT_ACCOUNT is recommended with appropriate scopes.
RESPONSE_TOO_LARGEStats are size-limited according to granularity in order to keep the response size under the threshold.
Check message field for a detailed explanation.
DUPLICATE_COMMANDCommand already in execution. Please try again later.
NOT_SUPPORTEDThis method is not supported for the OEM / Device

503 errors

ErrorDescription
MALFORMED_RESPONSEThe OEM servers are reachable, but the response received was not as expected.
Try again in some time.
NOT_SUPPORTEDThis method is not supported for this OEM / Device
QUOTA_EXCEEDEDAPI calls quota exceeded in OEM servers for this device. Try again in some time.
VENDOR_FAILUREReceived failure response from the vendor.
Vendor service might be down; please try again in some time
DEVICE_UNREACHABLEThe device is unreachable for remote commands/queries.
Make sure the device is connected to the internet, or try again later.
TELEMATICA_INTERNAL_ERRORInternal error in Telematica server.
The team will be notified of the issue.

500 errors

CHARGER_NOT_PLUGGEDThe charger is not plugged into any vehicle.
Please check the charger connection.
SUBSCRIPTION_EXPIREDThe user's OEM-connected service subscription has expired.
VEHICLE_NOT_PLUGGEDThe vehicle is not plugged in and hence cannot accept charging commands.
PRECONDITION_FAILEDA precondition failed while issuing a charging command. e.g. No Power to the Charger.

Fallback

Although this list of errors is exhaustive and all changes will be announced in our Changelog , It is recommended to setup a fallback in case of unhandled errors with 500 error code.

As a fallback, it is safe to forward the human-readablemessage field to the user.


Developer Actions

Action Description
SHOW_CONNECT_UIRedirect user to Connect UI to reconnect their OEM account.
The connection should be back to normal when action is performed.
PERMANENTLY_DELETE_DEVICEThe device has been removed from the associated OEM account.
The mapping can be permanently removed.
PROMPTA general suggestion to prompt end users to action with an appropriate message. The message field can be used as a reference prompt (for en-GB locale)