Errors and exceptions

This document lists the officially-supported errors and exceptions for smart home devices. Use these errors and exceptions to alert end users to issues related to a given command or device state.

Errors

You should return an error code when an issue causes an execute or query request to fail. For example, if a door lock is jammed and cannot be locked or unlocked, an error about this state should be returned to the user.

Error codes can be attached at the global level or at the device level. For example, if the user asks to turn off all their lights, a single provider may return a global-level error if their entire hub is offline and no lights can be controlled, or a device-level error if a single light is offline.

Global-level errors

{
  "requestId": "12345",
  "payload": {
    "errorCode": "inSoftwareUpdate"
  }
}

Device-level errors

{
  "requestId": "12345",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline"
      },
      "device-id-2": {
        "errorCode": "deviceOffline"
      }
    }
  }
}

Error list

The following errors will produce the associated TTS on the device.

  • actionNotAvailable : Sorry, I can't seem to do that right now.
  • alreadyAtMax : <device(s)> <is/are> already set to the maximum temperature.
  • alreadyAtMin : <device(s)> <is/are> already set to the minimum temperature.
  • alreadyDocked : <device(s)> <is/are> already docked.
  • alreadyInState : <device(s)> <is/are> already in that state.
  • alreadyOff : <device(s)> <is/are> already off.
  • alreadyOn : <device(s)> <is/are> already on.
  • alreadyPaused : <device(s)> <is/are> already paused.
  • alreadyStarted : <device(s)> <is/are> already started.
  • alreadyStopped : <device(s)> <is/are> already stopped.
  • appLaunchFailed : Sorry, failed to launch <app name> on <device(s)>.
  • authFailure : I can't seem to reach your <device(s)>. Try checking the app to make sure your device is fully set up.
  • binFull : <device(s)> <has/have> a full bin.
  • commandInsertFailed : Unable to process commands for <device(s)>.
  • degreesOutOfRange : The requested degrees are out of range for <device(s)>.
  • deviceNotFound : <device(s)> <is/are>n't available. You might want to try setting <it/them> up again.
  • deviceNotReady : <device(s)> <is/are> not ready.
  • deviceStuck : <device(s)> <is/are> stuck.
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
  • emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
  • functionNotSupported : Actually, that functionality isn't currently supported.
  • hardError : I'm sorry, there was an error and I'm unable to control your home device.
  • inAutoMode : <device(s)> <is/are> currently set to auto mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inAwayMode : <device(s)> <is/are> currently set to away mode. To control your thermostat, you'll need to manually switch it to home mode using the Nest app on a phone, tablet, or computer.
  • inDryMode : <device(s)> <is/are> currently set to dry mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inEcoMode : <device(s)> <is/are> currently set to eco mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inFanOnlyMode : <device(s)> <is/are> currently set to fan-only mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inHeatOrCool : <device(s)> <is/are> not in heat/cool mode.
  • inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inOffMode : <device(s)> <is/are> currently off. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inPurifierMode : <device(s)> <is/are> currently set to purifier mode. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inSleepMode : <device(s)> <is/are> in sleep mode. Please try again later.
  • lockedToRange : That temperature is outside the locked range on <device(s)>.
  • lowBattery : <device(s)> <has/have> low battery.
  • maxSpeedReached : <device(s)> <is/are> already set to the maximum speed.
  • minSpeedReached : <device(s)> <is/are> already set to the minimum speed.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> a software update.
  • needsWater : <device(s)> <need(s)> water.
  • noAvailableApp : Sorry, looks like <app name> is not available.
  • notSupported : That mode isn't available for <device(s)>.
  • obstructionDetected : <device(s)> detected an obstruction.
  • offline , deviceOffline : It looks like <device(s)> <is/are>n't available right now.
  • rangeTooClose : Those are too close for a Heat-Cool range for <device(s)>. Choose temperatures that are farther apart.
  • safetyShutOff : <device(s)> <is/are> in Safety Shut-Off Mode, so <it/they>'ll have to be adjusted by hand.
  • targetAlreadyReached : It looks like that's already the current temperature.
  • transientError : There was an error controlling <device(s)>. Please try again.
  • turnedOff , deviceTurnedOff : <device(s)> <is/are> off right now, so I can't make any adjustments.
  • valueOutOfRange : <device(s)> can't be set to that temperature.

Exceptions

You should return an exception when there is an issue or alert associated with a command. The command could succeed or fail.

If the command was successful (status = "SUCCESS"), report exceptions using the StatusReport trait (for devices other than the target), or by returning an appropriate exceptionCode (for the target device).

For example, if the dryer lint screen is full the user can still start their dryer, but you may want to warn them about this state. Similarly, when a device has a low battery that is not empty, you can still execute a command but should let them know that the device battery is low.

If the command fails due to exceptions, the status should be "EXCEPTIONS", and the exceptions should be reported using the StatusReport trait.

Non-blocking exception (SUCCESS) about target device

This example is for locking the door: The front door lock has low battery. Locking the front door.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

Non-blocking exception (SUCCESS) about another device using StatusReport

This example is for arming a security system: Ok, arming the security system. The front window is open.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "priority": 0,
          "statusCode": "windowOpen",
          "deviceTarget": "sensor_id1"
        }]
      }
    }]
  }
}

Blocking exception about another device using StatusReport

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",    // This is required for commands, not query
        "currentStatusReport": [{
            "blocking": true,
            "priority": 0,
            "statusCode": "lowBattery",
            "deviceTarget": "123"
          },
          {
            "blocking": true,
            "priority": 1,
            "deviceTarget": "front_window_id",
            "statusCode": "windowOpen"
          },
          {
            "blocking": true,
            "priority": 1,
            "deviceTarget": "back_window_id",
            "statusCode": "windowOpen"
          }
        ]
      }
    }
  }
}

Exception list

The following exceptions will produce the associated TTS on the device.

  • binFull : <device(s)> <has/have> a full bin.
  • carbonMonoxideDetected : Carbon monoxide has been detected in <house name>.
  • deviceMoved : <device(s)> <was/were> moved.
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • deviceUnplugged : <device(s)> <is/are> unplugged.
  • hardwareFailure : <device(s)> <has/have> a hardware problem.
  • inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
  • isBypassed : <device(s)> <is/are> currently bypassed.
  • lowBattery : <device(s)> <has/have> low battery.
  • motionDetected : <device(s)> <detect(s)> motion.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> a software update.
  • needsWater : <device(s)> <need(s)> water.
  • networkJammingDetected : the home network connection to <device(s)> is not working properly.
  • smokeDetected : Smoke has been detected in <house name>.
  • usingCellularBackup : <device(s)> <is/are> using cellular backup.
  • waterLeakDetected : <device(s)> <detect(s)> a water leak.