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.

  • aboveMaximumLightEffectsDuration : That's more than the maximum duration of 1 hour. Please try again.
  • 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.
  • amountAboveLimit : That's more than what <device(s)> can support.
  • 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.
  • bagFull : <device(s)> <has/have> (en.NumberAgreement singular='a full bag' plural='full bags' numeric_value=$item.target_names.size). Please empty <it/them> and try again.
  • belowMinimumLightEffectsDuration : That's less than the minimum duration of 5 minutes. Please try again.
  • binFull : <device(s)> <has/have> (en.NumberAgreement singular='a full bin' plural='full bins' numeric_value=$item.target_names.size).
  • commandInsertFailed : Unable to process commands for <device(s)>.
  • degreesOutOfRange : The requested degrees are out of range for <device(s)>.
  • deviceDoorOpen : The door is open on <device(s)>. Please close it and try again.
  • deviceLidOpen : The lid is open on <device(s)>. Please close it and try again.
  • deviceNotDocked : It looks like <device(s)> (en.NumberAgreement numeric_value=$item.target_names.size singular='isn\\'t' plural='aren\\'t') docked. Please dock <it/them> and try again.
  • 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.
  • doorClosedTooLong : It's been a while since the door on <device(s)> has been opened. Please open the door, make sure there's something inside, and try again.
  • emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
  • floorUnreachable : <device(s)> can't reach that room. Please move <it/them> to the right floor and try again.
  • 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.
  • maxSettingReached : <device(s)> <is/are> already set to the highest setting.
  • maxSpeedReached : <device(s)> <is/are> already set to the maximum speed.
  • minSettingReached : <device(s)> <is/are> already set to the lowest setting.
  • minSpeedReached : <device(s)> <is/are> already set to the minimum speed.
  • missingSubscription : It looks like you don't have an active subscription to this service. Please activate your subscription and try again.
  • needsAttachment : It looks like <device(s)> <is/are> missing a required attachment. Please replace it and try again.
  • needsBin : It looks like <device(s)> <is/are> missing a bin. Please replace it and try again.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> a software update.
  • needsWater : <device(s)> <need(s)> water.
  • noAvailableApp : Sorry, it 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.
  • onRequiresMode : Please specify which mode you want to turn on.
  • passphraseIncorrect : Sorry, the security code is incorrect.
  • pinIncorrect : (passphraseIncorrect)
  • rangeTooClose : Those are too close for a Heat-Cool range for <device(s)>. Choose temperatures that are farther apart.
  • relinkRequired : It looks like something went wrong with your account. Please use your Google Home or Assistant app to re-link <device(s)>.
  • roomsOnDifferentFloors : <device(s)> can't reach those rooms because they're on different floors.
  • safetyShutOff : <device(s)> <is/are> in Safety Shut-Off Mode, so <it/they>'ll have to be adjusted by hand.
  • tankEmpty : <device(s)> <has/have> (en.NumberAgreement numeric_value=$item.target_names.size singular='an empty tank' plural='empty tanks'). Please fill <it/them> and try again.
  • targetAlreadyReached : It looks like that's already the current temperature.
  • timerValueOutOfRange : <device(s)> can't be set for that amount of time.
  • 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.
  • unableToLocateDevice : I wasn't able to locate <device(s)>.
  • unknownFoodPreset : <device(s)> doesn't support that food preset.
  • 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,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

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,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}

Exception list

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

  • bagFull : <device(s)> <has/have> (en.NumberAgreement singular='a full bag' plural='full bags' numeric_value=$item.target_names.size). Please empty <it/them> and try again.
  • binFull : <device(s)> <has/have> (en.NumberAgreement singular='a full bin' plural='full bins' numeric_value=$item.target_names.size).
  • carbonMonoxideDetected : Carbon monoxide has been detected in <house name>.
  • deviceMoved : <device(s)> (en.NumberAgreement singular='was' plural='were' numeric_value=$item.target_names.size) moved.
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • deviceUnplugged : <device(s)> <is/are> unplugged.
  • floorUnreachable : <device(s)> can't reach that room. Please move <it/them> to the right floor and try again.
  • 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.
  • roomsOnDifferentFloors : <device(s)> can't reach those rooms because they're on different floors.
  • runCycleFinished : <device(s)> <has/have> finished running.
  • smokeDetected : Smoke has been detected in <house name>.
  • tankEmpty : <device(s)> <has/have> (en.NumberAgreement numeric_value=$item.target_names.size singular='an empty tank' plural='empty tanks'). Please fill <it/them> and try again.
  • usingCellularBackup : <device(s)> <is/are> using cellular backup.
  • waterLeakDetected : <device(s)> <detect(s)> a water leak.