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",
    "status" : "ERROR"
  }
}

Device-level errors

QUERY response

The following JSON snippet shows how you return device-level errors in the QUERY response.

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

EXECUTE response

The following JSON snippet shows how you return device-level errors in the EXECUTE response.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}

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.
  • aboveMaximumTimerDuration : I can only set <device(s)> for up to <time period>
  • actionNotAvailable : Sorry, I can't seem to do that right now.
  • actionUnavailableWhileRunning : <device(s)> <is/are> currently running, so I can't make any changes.
  • alreadyArmed : <device(s)> <is/are> already armed.
  • alreadyAtMax : <device(s)> <is/are> already set to the maximum temperature.
  • alreadyAtMin : <device(s)> <is/are> already set to the minimum temperature.
  • alreadyClosed : <device(s)> <is/are> already closed.
  • alreadyDisarmed : <device(s)> <is/are> already disarmed.
  • alreadyDocked : <device(s)> <is/are> already docked.
  • alreadyInState : <device(s)> <is/are> already in that state.
  • alreadyLocked : <device(s)> <is/are> already locked.
  • alreadyOff : <device(s)> <is/are> already off.
  • alreadyOn : <device(s)> <is/are> already on.
  • alreadyOpen : <device(s)> <is/are> already open.
  • alreadyPaused : <device(s)> <is/are> already paused.
  • alreadyStarted : <device(s)> <is/are> already started.
  • alreadyStopped : <device(s)> <is/are> already stopped.
  • alreadyUnlocked : <device(s)> <is/are> already unlocked.
  • amountAboveLimit : That's more than what <device(s)> can support.
  • appLaunchFailed : Sorry, failed to launch <app name> on <device(s)>.
  • armFailure : <device(s)> couldn't be armed.
  • armLevelNeeded : I'm not sure which level to set <device(s)> to. Try saying "Set <device(s)> to <low security>" or "Set <device(s)> to <high security>"
  • 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> <a full bag/full bags>. Please empty <it/them> and try again.
  • belowMinimumLightEffectsDuration : That's less than the minimum duration of 5 minutes. Please try again.
  • belowMinimumTimerDuration : I can't set <device(s)> for such a short time. Please try again.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • cancelArmingRestricted : Sorry, I could not cancel arming <device(s)>.
  • 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.
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceLidOpen : The lid is open on <device(s)>. Please close it and try again.
  • deviceNotDocked : Sorry, it looks like <device(s)> <isn't/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>n't 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.
  • disarmFailure : <device(s)> couldn't be disarmed.
  • 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 supported yet.
  • hardError : Sorry, something went wrong 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>n't 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.
  • lockFailure : <device(s)> couldn't be locked.
  • 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 : Sorry, it looks like you don't have an active subscription to this service. Please activate your subscription and try again.
  • needsAttachment : Sorry, it looks like <device(s)> <is/are> missing a required attachment. Please replace it and try again.
  • needsBin : Sorry, 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> isn't available.
  • notSupported : Sorry, that mode isn't available for <device(s)>.
  • obstructionDetected : <device(s)> detected an obstruction.
  • offline , deviceOffline : Sorry, 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 : Sorry, 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.
  • securityRestriction : <device(s)> <has/have> a security restriction.
  • startRequiresTime : To do that, you'll need to tell me how long you'd like to run <device(s)>.
  • tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
  • targetAlreadyReached : Sorry, it looks like that's already the current temperature.
  • timerValueOutOfRange : <device(s)> can't be set for that amount of time.
  • transientError : Sorry, something went wrong 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.
  • unlockFailure : <device(s)> couldn't be unlocked.
  • 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> <a full bag/full bags>. Please empty <it/them> and try again.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carbonMonoxideDetected : Carbon monoxide has been detected in <house name>.
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceMoved : <device(s)> <was/were> moved.
  • deviceOpen : <device(s)> <is/are> open.
  • 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)> isn't working properly.
  • roomsOnDifferentFloors : <device(s)> can't reach those rooms because they're on different floors.
  • runCycleFinished : <device(s)> <has/have> finished running.
  • securityRestriction : <device(s)> <has/have> a security restriction.
  • smokeDetected : Smoke has been detected in <house name>.
  • tankEmpty : <device(s)> <has/have> <an empty tank/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.