Error handling

Kotlin doesn't support checked exceptions. This simplifies and streamlines error handling, because you can choose to handle only those exceptions that are potentially recoverable. And because you don't have to explicitly handle every possible exception, your code is less cluttered and consequently, remains more focused on its primary purpose.

Recoverable failures are issues that a developer can address from their end. For example, if an ID used in a call is not valid, the API throws a HomeException with an invalid data message. The app developer can then choose to either remove that ID from their cache or show the user a message like "Structure not found".

An example of how one might handle a recoverable failure:

val result =
   try {
     homeManager.requestPermissions()
   } catch (e: HomeException) {
     PermissionsResult(
       PermissionsResultStatus.ERROR,
       "Got HomeException with error: ${e.message}",
     )
   }

Any method in the Home APIs can throw a HomeException, so we recommend that you use a try-catch block to catch HomeException on all calls.

When handling HomeException, check its code and message fields to learn what went wrong.

Any unhandled exceptions will result in your app crashing.

The following table provides the meanings of HomeException codes that you may encounter:

*Table: `HomeException` codes*
Code	Meaning
`ABORTED`	The operation was aborted. This typically appears when there's a concurrency issue such as a sequence check failure or transaction abort.
`ALREADY_EXISTS`	The resource or entity that you're trying to create already exists. This could be, for example, a named schedule for a thermostat.
`API_NOT_CONNECTED`	The client attempted to call a method from an API that failed to connect. This can happen when the device is offline or doesn't support the API you're attempting to call.
`CANCELLED`	The operation was cancelled, typically by the caller.
`DATA_LOSS`	Unrecoverable data loss or corruption.
`DEADLINE_EXCEEDED`	The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully.
`FAILED_PRECONDITION`	The operation was rejected because the system is not in a state required for the operation's execution. For example, you might get this message if you called `stop` on an oven that's already stopped.
`INTERNAL`	Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
`INVALID_ARGUMENT`	You provided an argument that is outside the expected range of values.
`NOT_FOUND`	You specified an entity or resource that can't be found. For example, specifying a nonexistent track id when calling `activateAudioTrack` on a media player device.
`OUT_OF_RANGE`	A parameter exceeded the valid range, based on the current system state. This message occurs when the value is within the range of values that the API call could potentially accept, but doesn't make sense in the present context.
`PERMISSION_DENIED`	You don't have permission to execute the specified operation. This error code shouldn't be interpreted to mean that the request is otherwise valid.
`RESOURCE_EXHAUSTED`	Some resource has been exhausted. For example, this could be thrown when one calls `dispense` on a pet feeder device and there's no more food left in the unit.
`SDK_INITIALIZATION_MISSING_INFO`	The SDK wasn't fully initialized. For example, you'll get this message if you try to get a `TraitFactory` for a trait that wasn't registered. See Initialization.
`UNAUTHENTICATED`	The caller cannot be identified or the request doesn't have valid authentication credentials.
`UNAVAILABLE`	The service is unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it's not always safe to retry non-idempotent operations.
`UNIMPLEMENTED`	The requested operation isn't implemented, supported or enabled in this service.
`UNKNOWN`	Unknown error. Generally speaking, `UNKNOWN` appears when an error condition occurs that can't be classified using any of the other error codes. For example, this error may be returned when a status value received from an external API that lacks sufficient information as to the root cause.