Sad paths and errors

Using APIs to read and control real-world devices is complex, and unexpected situations will inevitably occur in the physical world that your application should be prepared for.

Below are common exceptions to the typical happy path and best practices on how your application should handle them.

Copy linkMissing device capability

• Handling interventions for all the brands and capabilities you intend to support is critical for gracefully handling real-world issues that arise. Occasionally refer back to our documentation for the latest known interventions.
• Always check each device’s capabilities hash in the API to understand that specific unit’s capabilities. Even if a specific brand/model should support a capability, there are situations where a specific device will not!

Copy linkDeauthorized vendors and credentials refreshing

• The connection to Enode may become invalid due to external events. In these scenarios, the user will need to relink their account to your app via Enode.
• The connection to Enode becomes invalid, information about devices for that vendor will no longer be returned via the API and you will stop receiving updates about those devices. Relinking the same account will result in the data repopulating via the API with the same IDs as before.
• Listen to the user:credentials:invalidated webhook to learn about every time this happens.

Copy linkDeleted devices

• Your users may disassociate a device from their vendor account. Device data is permanently deleted from Enode when this happens.
• Listen to user:{vendorType}:deleted webhooks to learn about every time this happens.
• If the same real-world device is added back to a user’s vendor account, Enode will send a new user:{vendorType}:discovered webhook. Unlike with deauthorized vendors, historical data for the device will not be available and the device will have a new ID.

Copy linkAction preconditions not met

• Be sure to handle scenarios where actions are immediately created in the CANCELLED state. Actions such as Control ChargingAPI can be created in the CANCELLED state if we know that the action cannot be done.

Copy linkAction failures

• Actions may time out and fail after you create them. When you notice that an action has transitioned to FAILED, notify your users or begin a retry/recovery process.
• For vehicle charging actions, you can reference failureReason to understand why the charge action failed. The powerDeliveryState field can also provide additional details about whether a charger is functioning.

Copy linkOutdated device data

• Device connectivity, vendor cloud disruptions, and other issues often impact individual device freshness. Your application should have a built-in tolerance for data that may fall outside our typical freshness guidance.
• When available, rely on lastUpdated fields to determine the freshness of data itself. Use isReachable and lastSeen to determine connectivity with the vendor cloud and device.
• Refer to the Enode Status page to see if there are systemic issues affecting specific vendors.

Copy linkUnexpected smart charging behavior

• There are many factors at play that can affect how smart charging works in practice. To reduce confusion, be sure to educate your users on some of the most common issues such as:
  • Not having any other 1st or 3rd party apps or schedules control charging
  • Smart charging will only work when energy savings is sufficient
  • A vehicle may begin charging immediately when plugged in when a smart charging plan is in the CONSIDERING state
• Be sure to listen to the PLAN events for the best information on why smart charging is behaving a certain way.
• Refer to our detailed smart charging guide for more information.

Copy linkBest practices for error handling

Your integration should include robust error handling to provide the best user experience possible and minimize frustration when things go wrong. Refer to our API ReferenceAPI for a detailed list of error codes.

When handling errors, follow these best practices:

• Consider implementing a hierarchy of error handling:
  • Build explicit handling for sad paths you know and care about. Treat these as first-class product features with polished designs and recovery paths
  • Unexpected vendor issues should be communicated as such as not to question the reliability of your own application. Prompt the user to try again later
  • For all other errors, use generic error messaging
• Keeping a log of state changes for a device or action to enable easier debugging and allows Enode to better support you diagnosing potential issues