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 app503
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). Themessage
field, in this case, contains the details of the error along with a call to action.
412
errors
412
errorsError | Description |
---|---|
NOT_FOUND | Device entry not found |
RELOGIN_REQUIRED | The user changed credentials for the OEM account or revoked access Action RECONNECT_ACCOUNT is recommended. |
DEVICE_DISCONNECTED | The specific device has been disconnected from the OEM account. Action PERMANENTLY_DELETE_DEVICE is recommended. |
INVALID_REQUEST | The request body is invalid. Check message field for a detailed explanation. |
USER_CONSENT_REQUIRED | The requested device/data point is out of scope for your app. Action RECONNECT_ACCOUNT is recommended with appropriate scopes. |
RESPONSE_TOO_LARGE | Stats are size-limited according to granularity in order to keep the response size under the threshold. Check message field for a detailed explanation. |
DUPLICATE_COMMAND | Command already in execution. Please try again later. |
NOT_SUPPORTED | This method is not supported for the OEM / Device |
503
errors
503
errorsError | Description |
---|---|
MALFORMED_RESPONSE | The OEM servers are reachable, but the response received was not as expected. Try again in some time. |
NOT_SUPPORTED | This method is not supported for this OEM / Device |
QUOTA_EXCEEDED | API calls quota exceeded in OEM servers for this device. Try again in some time. |
VENDOR_FAILURE | Received failure response from the vendor. Vendor service might be down; please try again in some time |
DEVICE_UNREACHABLE | The device is unreachable for remote commands/queries. Make sure the device is connected to the internet, or try again later. |
TELEMATICA_INTERNAL_ERROR | Internal error in Telematica server. The team will be notified of the issue. |
500
errors
500
errorsCHARGER_NOT_PLUGGED | The charger is not plugged into any vehicle. Please check the charger connection. |
SUBSCRIPTION_EXPIRED | The user's OEM-connected service subscription has expired. |
VEHICLE_NOT_PLUGGED | The vehicle is not plugged in and hence cannot accept charging commands. |
PRECONDITION_FAILED | A 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_UI | Redirect user to Connect UI to reconnect their OEM account. The connection should be back to normal when action is performed. |
PERMANENTLY_DELETE_DEVICE | The device has been removed from the associated OEM account. The mapping can be permanently removed. |
PROMPT | A 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) |
Updated 4 months ago