Errors and handling

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

Suggest Edits

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 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 end user's intervention (Ex. charger not plugged in to 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_REQUIREDUser changed credentials for OEM account, or revoked access
Action RECONNECT_ACCOUNT is recommended.
DEVICE_DISCONNECTEDThe specific device has been disconnected from OEM account.
Action PERMANENTLY_DELETE_DEVICE is recommended.
INVALID_REQUESTRequest body is invalid. Check message field for 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 threshold.
Check message field for detailed explanation.
DUPLICATE_COMMANDCommand already in execution. Please try again later.

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 vendor.
Vendor service might be down, please try again in some time
DEVICE_UNREACHABLEThe device is unreachable for remote commands / query.
Make sure the device is connected to internet, or try again later.
TELEMATICA_INTERNAL_ERRORInternal error in Telematica server.
The team will be notified of the issue.

500 errors

CHARGER_NOT_PLUGGEDCharger is not plugged to any vehicle.
Please check the charger connection.
SUBSCRIPTION_EXPIREDUser's OEM connected service subscription has expired
VEHICLE_NOT_PLUGGEDVehicle is not plugged in, and hence cannot accept charging commands.

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 readable message 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 user for action with appropriate message. The message field can be used as reference prompt (for en-GB locale)

Updated about 2 months ago