Errors and exceptions

This document lists the officially-supported errors and exceptions for smart home devices. Please use these given errors and exceptions codes in the intent response, or in notifications if you have implemented it, so Google Assistant alerts end users to issues related to a given command or device state. If the response contains incorrect formatting or errorCode, Google Assistant gives users a generic error message, for example, "Sorry, device is not available right now".

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 device level or at the global level. For example, if a user has many lights from one provider and they are controlled by a hub, when the user asks to turn off all their lights, the provider may return a device-level error if a single light is offline, or a global-level error if their entire hub is offline and no lights can be controlled. If all the devices are offline, there is no difference between using global-level or device-level errors.

When a device is offline, you should report {"online": false} to Report State within 5 minutes of the device's behavior.

In summary:

  • Global-level error: all the devices in the response have the same error
  • Local-level error: mixed response with error and success cases

Global-level errors

The following JSON snippet shows how you return global-level errors in either QUERY or EXECUTE response.

An example of global-level error deviceOffline due to the hub is offline:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

An example of global-level error inSoftwareUpdate due to the hub is updating:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "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": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "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": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

Notifications with errors

Proactive notification

The following JSON snippet shows how you report device-level errors in a proactive notification.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

Follow-up response

The following JSON snippet shows how you report device-level errors in a follow-up response.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

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.
  • ambiguousZoneName : Sorry, <device(s)> can't identify which zone you mean. Please make sure your zones have unique names and try again.
  • 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 <device(s)>. Try checking the app to make sure your <device/devices> <is/are> 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 couldn't cancel arming <device(s)>.
  • cancelTooLate : Sorry, it's too late to cancel. Use <device(s)> or the app instead.
  • channelSwitchFailed : Sorry, failed to switch to channel <channel name>. Please try again later.
  • chargerIssue : Sorry, it looks like <device(s)> <has/have> <a charger issue/charger issues>.
  • commandInsertFailed : Unable to process commands for <device(s)>.
  • deadBattery : <device(s)> <has/have> <a dead battery/dead batteries>.
  • degreesOutOfRange : The requested degrees are out of range for <device(s)>.
  • deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.
  • deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
  • deviceBusy : Sorry, it looks like <device(s)> is already doing something right now.
  • deviceCharging : Sorry, it looks like <device(s)> can't do that because (ha_shared.ItsTheyre size=$item.devices.total_device_count) charging.
  • deviceClogged : Sorry, it looks like <device(s)> is clogged.
  • deviceCurrentlyDispensing : <device(s)> is already dispensing something right now.
  • deviceDoorOpen : The door is open on <device(s)>. Please close it and try again.
  • deviceHandleClosed : The handle is closed on <device(s)>. Please open it and try again.
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceLidOpen : The lid is open on <device(s)>. Please close it and try again.
  • deviceNeedsRepair : <device(s)> <need(s)> to be repaired. Please contact your local service dealer.
  • 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.
  • deviceNotMounted : Sorry, it looks like <device(s)> can't do that because <it/they> <is/are>n't mounted.
  • deviceNotReady : <device(s)> <is/are>n't ready.
  • deviceStuck : <device(s)> <is/are> stuck and needs your help.
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • deviceThermalShutdown : Sorry, it looks like <device(s)> shut down due to extreme temperatures.
  • directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
  • disarmFailure : <device(s)> couldn't be disarmed.
  • discreteOnlyOpenClose : Sorry, <device(s)> can only be opened or closed all the way.
  • dispenseAmountAboveLimit : <device(s)> can't dispense such a large amount.
  • dispenseAmountBelowLimit : <device(s)> can't dispense such a small amount.
  • dispenseAmountRemainingExceeded : <device(s)> doesn't have enough <dispense item> to do that.
  • dispenseFractionalAmountNotSupported : <device(s)> can't dispense fractions of <dispense item>.
  • dispenseFractionalUnitNotSupported : <device(s)> doesn't support fractions of that unit for <dispense item>.
  • dispenseUnitNotSupported : <device(s)> doesn't support that unit for <dispense item>.
  • 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.
  • faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
  • floorUnreachable : <device(s)> can't reach that room. Please move <it/them> to the right floor and try again.
  • functionNotSupported : Actually, <device(s)> <doesn't/don't> support that functionality.
  • genericDispenseNotSupported : I need to know what you would like to dispense. Please try again with the name of the item.
  • hardError : Sorry, something went wrong and I'm unable to control your home device.
  • 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.
  • inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
  • lockFailure : <device(s)> couldn't be locked.
  • lockedState : <device(s)> <is/are> currently 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.
  • monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
  • 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.
  • networkProfileNotRecognized : Sorry, I don't recognize "<network profile>" on <device(s)>.
  • networkSpeedTestInProgress : I'm already testing the <network> <speed/speeds>>.
  • noAvailableApp : Sorry, it looks like <app name> isn't available.
  • noAvailableChannel : Sorry, it looks like channel <channel name> isn't available.
  • noChannelSubscription : Sorry, you aren't subscribed to channel <channel name> at the moment.
  • noTimerExists : Sorry, it looks like there aren't any timers set on <device(s)>.
  • 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, it looks like that PIN is incorrect.
  • percentOutOfRange : Sorry, I can't set <device(s)> to <percent>.
  • pinIncorrect : (passphraseIncorrect)
  • rainDetected : I didn't open <device(s)> because rain was detected.
  • 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)>.
  • remoteSetDisabled :
    • Optional parameter errorCodeReason
    • currentlyArmed - Sorry, since security is already armed, you need to use <device(s)> or the app to make any changes.
    • remoteUnlockNotAllowed - Sorry, I can't unlock <device(s)> remotely.
    • remoteControlOff - That action is currently disabled. Please enable remote control on <device(s)> and try again.
    • childSafetyModeActive - That action is disabled for <device(s)> while child safety mode is active.
  • 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.
  • sceneCannotBeApplied : Sorry, <device(s)> can't be applied.
  • securityRestriction : <device(s)> <has/have> a security restriction.
  • softwareUpdateNotAvailable : Sorry, there's no software update available on <device(s)>.
  • startRequiresTime : To do that, you'll need to tell me how long you'd like to run <device(s)>.
  • stillCoolingDown : <device(s)> <is/are> still cooling down.
  • stillWarmingUp : <device(s)> <is/are> still warming up.
  • streamUnavailable : Sorry, it looks like the stream is currently unavailable from <device(s)>.
  • streamUnplayable : Sorry, I can't play the stream from <device(s)> at the moment.
  • 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.
  • tooManyFailedAttempts : Sorry, too many failed attempts. Please go to your device's app to complete that action.
  • transientError : Sorry, something went wrong controlling <device(s)>. Please try again.
  • turnedOff , deviceTurnedOff : <device(s)> <is/are> off right now.
  • 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.
  • unpausableState : <device(s)> can't be paused right now.
  • userCancelled : ok
  • 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": ["device-id-1"],
      "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": ["device-id-1"],
      "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": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "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>.
  • deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
  • 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.
  • noIssuesReported : <device(s)> reported no issues.
  • 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.