Ошибки и исключения

В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Используйте приведенные ниже коды ошибок и исключений в ответе на намерение или в уведомлениях, если вы их настроили. Тогда Google Ассистент будет сообщать конечным пользователям о проблемах, связанных с определенной командой или состоянием устройства. Если ответ содержит неправильное форматирование или errorCode, Google Ассистент показывает пользователям общее сообщение об ошибке, например "Извините, устройство сейчас недоступно".

Ошибки

Если запрос на выполнение или запрос к базе данных не удается выполнить, необходимо вернуть код ошибки. Например, если дверной замок заклинило и его нельзя запереть или отпереть, пользователь должен получить сообщение об ошибке.

Коды ошибок могут быть прикреплены на уровне устройства или на глобальном уровне. Например, если у пользователя много светильников от одного поставщика и они управляются через хаб, когда пользователь просит выключить все свои светильники, поставщик может вернуть ошибку на уровне устройства, если один светильник находится в автономном режиме, или глобальную ошибку, если весь его хаб находится в автономном режиме и никакими светильниками нельзя управлять. Если все устройства офлайн, то нет разницы, какие ошибки использовать – на уровне устройства или глобальные.

Сводные указания:

  • Ошибка на глобальном уровне: у всех устройств в ответе одна и та же ошибка.
  • Ошибка на локальном уровне: смешанный ответ с ошибками и успешными операциями

Ошибки на глобальном уровне

В следующем фрагменте JSON показано, как возвращать ошибки глобального уровня в ответе QUERY или EXECUTE.

Пример ошибки глобального уровня deviceOffline, связанной с тем, что контроллер не подключен к интернету:

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

Пример ошибки глобального уровня inSoftwareUpdate из-за обновления концентратора:

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

Ошибки на уровне устройства

Ответ QUERY

В следующем фрагменте JSON показано, как возвращать ошибки на уровне устройства в ответе QUERY.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

Ответ EXECUTE

В следующем фрагменте JSON показано, как возвращать ошибки на уровне устройства в ответе EXECUTE.

{
  "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
        }
      }
    ]
  }
}

Уведомления с ошибками

Умные уведомления

В следующем фрагменте JSON показано, как сообщить об ошибках на уровне устройства в умном уведомлении.

{
  "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"
          }
        }
      }
    }
  }
}

Ответ на последующий запрос

В следующем фрагменте JSON показано, как сообщить об ошибках на уровне устройства в последующем ответе.

{
  "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"
            }
          }
        }
      }
    }
  }
}

Список ошибок

При возникновении следующих ошибок на устройстве будет воспроизводиться соответствующее сообщение.

  • aboveMaximumLightEffectsDuration : Это больше максимальной продолжительности в 1 час. Повторите попытку.
  • aboveMaximumTimerDuration : Я могу установить таймер на <device(s)> максимум на <time period>.
  • actionNotAvailable : Извините, сейчас у меня не получается это сделать. Совет. Проверьте логику работы функций и текущего состояния устройства в своем ответе на запрос.
  • actionUnavailableWhileRunning : <device(s)> <is/are> currently running, so I can't make any changes.
  • alreadyArmed : <device(s)> <is/are> already armed.
  • alreadyAtMax : На устройстве <device(s)> уже установлена максимальная температура.
  • alreadyAtMin : На устройстве <device(s)> уже установлена минимальная температура.
  • 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 : <device(s)> не может определить, какую зону вы имеете в виду. Убедитесь, что у зон уникальные названия, и повторите попытку.
  • amountAboveLimit : Эта функция не поддерживается на устройстве <device(s)>.
  • appLaunchFailed : Не удалось запустить приложение <название приложения> на устройстве <название устройства>. Совет. Проверьте идентификатор приложения и убедитесь, что оно поддерживается на целевом оборудовании.
  • armFailure : Не удалось включить режим охраны на устройствах: <device(s)>.
  • armLevelNeeded : Я не понимаю, какой уровень безопасности нужно установить для <device(s)>. Скажите, например, "Установи <низкий уровень безопасности> на <устройстве>" или "Установи <высокий уровень безопасности> на <устройстве>".
  • authFailure : Не удается подключиться к устройству <device(s)>. Перейдите в приложение и убедитесь, что устройство <device/devices> полностью настроено.
  • bagFull : Пылесборник устройства <device(s)> переполнен. Опустошите его и повторите попытку.
  • belowMinimumLightEffectsDuration : Это меньше минимальной продолжительности (5 минут). Повторите попытку.
  • belowMinimumTimerDuration : Я не могу установить на <device(s)> такое короткое время. Повторите попытку.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • cancelArmingRestricted : Не удалось отменить постановку на охрану.
  • cancelTooLate : К сожалению, отменить бронирование уже нельзя. Используйте <device(s)> или приложение.
  • channelSwitchFailed : Извините, мне не удалось включить канал <название канала>.Повторите попытку позже. Совет. Проверьте названия и номера каналов, а также статус подписки пользователя.
  • chargerIssue : Похоже, с зарядным устройством <device(s)> возникла проблема. Совет. Партнеру следует проверить телеметрию на уровне оборудования и состояние батареи.
  • commandInsertFailed : Не удалось обработать команды для <device(s)>. Совет. Проверьте производительность записи в базу данных или логику внутренней очереди команд.
  • deadBattery : Батарея устройства <device(s)> разряжена.
  • degreesOutOfRange : Запрошенное значение не входит в допустимый диапазон устройства <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 : Похоже, устройство <device(s)> уже что-то делает.
  • deviceCharging : Похоже, <device(s)> заряжается и не может выполнить это действие.
  • deviceClogged : Похоже, устройство <device(s)> засорилось.
  • deviceCurrentlyDispensing : <device(s)> уже начало выдачу.
  • deviceDoorOpen : Дверца устройства <device(s)> открыта. Закройте ее и повторите попытку.
  • deviceHandleClosed : Ручка закрыта на следующих устройствах: <device(s)>. Откройте ее и повторите попытку.
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceLidOpen : Крышка устройства <device(s)> открыта. Закройте ее и повторите попытку.
  • deviceNeedsRepair : <device(s)> <need(s)> to be repaired. Обратитесь в местный сервисный центр.
  • deviceNotDocked : Похоже, устройство <device(s)> не подключено к док-станции. Подключите <его/их> и повторите попытку.
  • deviceNotFound : <device(s)> <is/are>n't available. Попробуйте настроить <it/them> заново. Совет. Убедитесь, что ваш сервер всегда синхронизирует Home Graph. Вызывайте requestSync при добавлении или удалении устройств.
  • deviceNotMounted : Это действие недоступно для устройства <device(s)>, так как оно не установлено.
  • 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 : <Устройство> отключилось из-за слишком высокой или слишком низкой температуры.
  • directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
  • disarmFailure : Не удалось отключить сигнализацию на устройствах: <device(s)>.
  • discreteOnlyOpenClose : <Device(s)> можно только открыть или закрыть полностью.
  • dispenseAmountAboveLimit : <device(s)> не может выдавать так много.
  • dispenseAmountBelowLimit : <device(s)> не может выдавать так мало.
  • dispenseAmountRemainingExceeded : На устройстве <device(s)> недостаточно <dispense item>.
  • dispenseFractionalAmountNotSupported : <device(s)> не может выдать дробное количество <dispense item>.
  • dispenseFractionalUnitNotSupported : <device(s)> не поддерживает дробные числа для этой единицы измерения количества <dispense item>.
  • dispenseUnitNotSupported : <device(s)> не поддерживает эту единицу измерения для <dispense item>.
  • doorClosedTooLong : Дверца на устройстве <device(s)> долго была закрыта. Откройте её и убедитесь, что внутри не пусто, а затем попробуйте снова.
  • emergencyHeatOn : <device(s)> <is/are> в режиме вспомогательного отопления, поэтому <it/they> нужно настроить вручную.
  • faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
  • floorUnreachable : <device(s)> can't reach that room. Перенесите <it/them> на нужный этаж и повторите попытку.
  • functionNotSupported : <device(s)> не поддерживает эту функцию. Совет. Убедитесь, что ответ SYNC точно отражает возможности устройства.
  • genericDispenseNotSupported : Мне нужно знать, что вы хотите выдать. Повторите запрос, указав название товара.
  • hardError : Произошла ошибка. Я не могу управлять вашим устройством умного дома.
  • hardError : Произошла ошибка. Я не могу управлять вашим устройством умного дома.
  • inAutoMode : <device(s)> <is/are> currently set to auto mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inAwayMode : <device(s)> <is/are> currently set to away mode. Чтобы управлять термостатом, вам нужно вручную переключить его в режим "Я дома" в приложении Nest на телефоне, планшете или компьютере.
  • inDryMode : <device(s)> <is/are> currently set to dry mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inEcoMode : <device(s)> <is/are> currently set to eco mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inFanOnlyMode : <device(s)> <is/are> currently set to fan-only mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
  • inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inOffMode : <device(s)> сейчас выключены. Чтобы изменить температуру, переключите их в другой режим.
  • inPurifierMode : <device(s)> <is/are> currently set to purifier mode. Чтобы изменить температуру, переключите <it/them> в другой режим.
  • inSleepMode : <device(s)> <is/are> in sleep mode. Повторите попытку позже.
  • inSoftwareUpdate : На <device(s)> сейчас устанавливается обновление ПО.
  • lockFailure : Не удалось заблокировать устройство <device(s)>. Совет. Проверьте, нет ли физических помех, низкого заряда батареи или неисправностей мотора в замке.
  • lockedState : <device(s)> <is/are> currently locked.
  • lockedToRange : Эта температура выходит за пределы диапазона, установленного на устройстве <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 : Похоже, на устройстве <device(s)> отсутствует нужная насадка. Установите ее и повторите попытку.
  • needsBin : Похоже, на <device(s)> отсутствует пылесборник. Установите ее и повторите попытку.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> a software update.
  • needsWater : <device(s)> <need(s)> water.
  • networkProfileNotRecognized : Извините, я не знаю профиль сети "<network profile>" на устройстве <device(s)>. Совет. Убедитесь, что название профиля совпадает с поддерживаемыми профилями в ответе SYNC.
  • networkSpeedTestInProgress : Я уже проверяю <скорость/скорости> <сети>.
  • noAvailableApp : Похоже, приложение <название приложения> недоступно.
  • noAvailableChannel : Похоже, канал <название канала> недоступен.
  • noChannelSubscription : Вы пока не подписаны на канал <название канала>.
  • noTimerExists : Похоже, на устройстве <device(s)> нет запущенных таймеров.
  • notSupported : Этот режим недоступен для устройства <device(s)>.
  • obstructionDetected : <device(s)> detected an obstruction.
  • offline , deviceOffline : Похоже, устройство <device(s)> сейчас недоступно.
  • onRequiresMode : Укажите, какой режим вы хотите включить.
  • passphraseIncorrect : Похоже, PIN-код неверный.
  • percentOutOfRange : Извините, я не могу установить <percent> для <device(s)>.
  • pinIncorrect : (passphraseIncorrect)
  • rainDetected : Мне пришлось оставить <device(s)> закрытым, так как был зафиксирован дождь.
  • rangeTooClose : Диапазон температур для режима "Обогрев и охлаждение" на устройстве <device(s)> слишком узкий. Выберите температуры, которые находятся дальше друг от друга.
  • relinkRequired .Похоже, что-то не так с вашим аккаунтом. Повторно свяжите <device(s)> с помощью приложения Google Home или Помощник. Совет. Убедитесь, что ваш сервер возвращает этот код, когда токен обновления становится недействительным.
  • remoteSetDisabled :
    • Необязательный параметр errorCodeReason
    • currentlyArmed – Поскольку сигнализация уже включена, вы можете внести изменения только через <устройство> или приложение.
    • remoteUnlockNotAllowed – К сожалению, я не могу разблокировать устройство или устройства удаленно.
    • remoteControlOff – Действие недоступно. Включите дистанционное управление на устройстве <device(s)> и повторите попытку.
    • childSafetyModeActive – Это действие недоступно для устройства <device(s)>, поскольку включён режим безопасности для детей.
  • roomsOnDifferentFloors : <device(s)> не может попасть в эти комнаты, потому что они находятся на разных этажах.
  • safetyShutOff : <device(s)> <is/are> в режиме аварийного отключения, поэтому <it/they> нужно настроить вручную.
  • sceneCannotBeApplied : Не удалось применить сцену к устройству <device(s)>. Совет. Проверьте состояние сцен пользователя в облаке партнера.
  • securityRestriction : <device(s)> <has/have> a security restriction.
  • softwareUpdateNotAvailable : Обновлений для устройства <device(s)> нет.
  • startRequiresTime : Для этого скажите, на сколько нужно поставить таймер на <device(s)>.
  • stillCoolingDown : <device(s)> <is/are> still cooling down.
  • stillWarmingUp : <device(s)> <is/are> still warming up.
  • streamUnavailable : Похоже, трансляция с устройства <device(s)> сейчас недоступна.
  • streamUnplayable : Извините, сейчас я не могу воспроизвести трансляцию с устройства <device(s)>. Совет. Проверьте сигнализацию WebRTC/HLS и убедитесь, что URL трансляции действителен.
  • tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
  • targetAlreadyReached : Похоже, такая температура уже установлена.
  • timerValueOutOfRange : Нельзя установить таймер на такое время на устройстве <устройство>.
  • tooManyFailedAttempts : Слишком много неудачных попыток. Чтобы выполнить это действие, перейдите в приложение на устройстве.
  • transientError : При использовании устройства <device(s)> что-то пошло не так. Повторите попытку. Совет. Чаще всего эти ошибки проявляются как сброс подключения к устройству или сервису. или если не удается установить новые подключения к серверу.
  • turnedOff , deviceTurnedOff : <device(s)> сейчас не работает.
  • unableToLocateDevice : Мне не удалось найти <device(s)>. Совет. Проверьте подключение устройства к локальной сети (Wi-Fi/Bluetooth).
  • unknownFoodPreset : <device(s)> не поддерживает такой режим приготовления.
  • unlockFailure : Не удалось разблокировать устройство или устройства. Совет. Проверьте, не заклинило ли замок, не разрядилась ли батарея и правильно ли введен PIN-код.
  • unpausableState : Сейчас нельзя приостановить работу устройства <device(s)>.
  • userCancelled : ok
  • valueOutOfRange : Для устройства <device(s)> нельзя установить такую температуру.

Отчеты о статусе онлайн и офлайн

Если устройство находится в офлайн-режиме, вы должны сообщить <code{"online": code="" dir="ltr" false}<="" translate="no"> в Report State в течение пяти минут после изменения поведения устройства. И наоборот, когда устройство снова подключается к интернету, вы должны сообщить <code{"online": code="" dir="ltr" translate="no" true}<=""> в Report State в течение пяти минут после изменения поведения устройства. Когда устройство снова подключается к интернету, партнер должен сообщить обо всех текущих состояниях устройства с помощью reportStateAndNotification API. В этом примере показано, что устройство типа light находится в сети, и сообщается о всех текущих состояниях устройства.
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Исключения

Исключение следует возвращать, когда с командой связана проблема или оповещение. Команда может быть выполнена успешно или нет.

Если команда выполнена успешно (status = "SUCCESS"), сообщите об исключениях, используя свойство StatusReport (для устройств, отличных от целевого) или возвращая соответствующий exceptionCode (для целевого устройства).

Например, если фильтр сушилки заполнен, пользователь все равно может запустить сушилку, но вы можете предупредить его об этом состоянии. Аналогично, если батарея устройства разряжена, но не полностью, вы можете выполнить команду, но должны сообщить пользователю о низком заряде батареи.

Если команда не выполнена из-за исключений, статус должен быть "EXCEPTIONS", а исключения должны быть указаны с помощью типажа StatusReport.

Неблокирующее исключение (SUCCESS) для целевого устройства

Пример для запирания двери:

У замка входной двери низкий заряд батареи. Запираю входную дверь.

{
  "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"
      }
    }]
  }
}

Неблокирующее исключение (SUCCESS), связанное с другим устройством, использующим StatusReport

Пример для включения охранной системы: Хорошо, включаю охранную систему. Окно впереди открыто.

{
  "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"
        }]
      }
    }]
  }
}

Исключение, связанное с блокировкой другого устройства, использующего 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"
          }
        ]
      }
    }
  }
}

Список исключений

Ниже перечислены исключения, при которых на устройстве будет воспроизводиться соответствующее сообщение.

  • bagFull : Пылесборник устройства <device(s)> переполнен. Опустошите его и повторите попытку.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carbonMonoxideDetected : В доме <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. Перенесите <it/them> на нужный этаж и повторите попытку.
  • hardwareFailure : <device(s)> <has/have> a hardware problem.
  • inSoftwareUpdate : На <device(s)> сейчас устанавливается обновление ПО.
  • 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 : Возникли проблемы с подключением <устройства/устройств> к домашней сети.
  • noIssuesReported : <device(s)> reported no issues.
  • roomsOnDifferentFloors : <device(s)> не может попасть в эти комнаты, потому что они находятся на разных этажах.
  • runCycleFinished : <device(s)> <has/have> finished running.
  • securityRestriction : <device(s)> <has/have> a security restriction.
  • smokeDetected : В доме <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.
</code{"online":></code{"online":>