Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones para el hogar inteligente. Nota: Continuarás compilando acciones en la Consola de Actions.

Errores y excepciones

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En este documento, se enumeran las excepciones y los errores compatibles oficialmente con los dispositivos de casa inteligente. Usa estos códigos de excepciones y errores en la respuesta del intent, o en las notificaciones, si lo implementaste. Así, Asistente de Google alerta a los usuarios finales sobre problemas relacionados con un comando o el estado de un dispositivo determinado. Si la respuesta contiene un formato incorrecto o errorCode, Asistente de Google les muestra a los usuarios un mensaje de error genérico, por ejemplo, "Lo siento, el dispositivo no está disponible en este momento".

Errores

Debes mostrar un código de error cuando un problema hace que una solicitud de ejecución o consulta falle. Por ejemplo, si un bloqueo de puerta está atascado y no se puede trabar o destrabar, se debe mostrar al usuario un error sobre este estado.

Los códigos de error se pueden adjuntar a nivel del dispositivo o a nivel global. Por ejemplo, si un usuario tiene muchas luces de un proveedor y un concentrador lo controla, cuando el usuario solicita apagar todas las luces, es posible que el proveedor muestre un error a nivel del dispositivo si una sola luz está sin conexión, o un error de nivel global si todo el concentrador está sin conexión y no se puede controlar ninguna luz. Si todos los dispositivos están sin conexión, no hay diferencia entre el uso de errores a nivel global o de dispositivo. Cuando un dispositivo no tiene conexión, debes informar el estado {"online": false} en reportState, incluso si muestras el código de error deviceOffline.

En resumen, haz lo siguiente:

  • Error a nivel global: todos los dispositivos en la respuesta tienen el mismo error
  • Error a nivel local: respuesta mixta con casos de error y éxito

Errores a nivel global

En el siguiente fragmento JSON, se muestra cómo mostrar errores a nivel global en la respuesta QUERY o EXECUTE.

Un ejemplo de error de nivel global deviceOffline debido a Hub es sin conexión:

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

Se está actualizando un ejemplo de error de nivel global inSoftwareUpdate debido a Hub:

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

Errores a nivel del dispositivo

QUERY respuesta

En el siguiente fragmento JSON, se muestra cómo mostrar errores a nivel del dispositivo en la respuesta de QUERY.

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

Respuesta de EXECUTE

En el siguiente fragmento JSON, se muestra cómo mostrar errores a nivel del dispositivo en la respuesta EJECUTA.

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

Notificaciones con errores

Notificación proactiva

En el siguiente fragmento JSON, se muestra cómo informar errores a nivel del dispositivo en una notificación proactiva.

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

Respuesta de seguimiento

En el siguiente fragmento JSON, se muestra cómo informar errores a nivel del dispositivo en una respuesta de seguimiento.

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

Lista de errores

Los siguientes errores producirán el TTS asociado en el dispositivo.

  • maxmaximumLightEffectsDuration : Eso es más de la duración máxima de 1 hora. Vuelve a intentarlo.
  • abovemaximumTimerDuration : Solo puedo configurar <device(s)> por un máximo de <time period>
  • actionNotAvailable : Lamentablemente, no puedo hacerlo en este momento.
  • actionUnavailableWhenRunning : <device(s)> <is/are> se está ejecutando, por lo que no puedo hacer cambios.
  • Ya armado : <device(s)> <is/are> already enabled.
  • alreadyAtMax : <device(s)> <is/are> ya se estableció en la temperatura máxima.
  • alreadyAtMin : <device(s)> <is/are> ya se estableció en la temperatura mínima.
  • ya cerrada : <dispositivo(s)> <is/are> ya está cerrado.
  • Ya desarmado : <dispositivo(s)> <is/are> ya se desactivó.
  • Ya está conectado : <device(s)> <is/are> already Dock.
  • ya existente : <device(s)> <is/are> already in that state.
  • Ya está bloqueado : <dispositivo(s)> <is/are> ya está bloqueado.
  • OffOff : <device(s)> <is/are> ya está desactivado.
  • Ya activado : <device(s)> <is/are> already on.
  • ya está abierta : <device(s)> <is/are> already open.
  • alreadyPaused : <device(s)> <is/are> ya se detuvo.
  • Ya se inició : <dispositivo(s)> <is/are> ya se inició.
  • alreadyStopped : <dispositivo(s)> <is/are> ya se detuvo.
  • Ya desbloqueado : <dispositivo(s)> <is/are> ya está desbloqueado.
  • ambiguousZoneName : Lo sentimos, <device(s)> no puede identificar la zona a la que te refieres. Asegúrate de que las zonas tengan nombres únicos y vuelve a intentarlo.
  • amountAboveLimit : Eso es más de lo que admiten los <device(s)>.
  • appLaunchFailed : No se pudo iniciar <app name> en <device(s)>.
  • armFailure : <device(s)> no se pudo activar.
  • armLevelNeeded : No sé en qué nivel establecer <device(s)>. Di "Establecer <dispositivo(s)> en <baja seguridad>" o "Establecer <dispositivo(s)> en <alta seguridad>"
  • authFailure : No puedo establecer conexión con <device(s)>. Verifica la app para asegurarte de que tu <device/devices> <is/are> esté completamente configurado.
  • bagFull : <device(s)> <has/have> <a full bag/full Bag>.. Vacía <it/them> y vuelve a intentarlo.
  • belowMinimumLightEffectsDuration : Eso es inferior a la duración mínima de 5 minutos. Vuelve a intentarlo.
  • belowMinimumTimerDuration : No puedo establecer <device(s)> por tan poco tiempo. Vuelve a intentarlo.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • cancelArmingRestricted : Lo siento, no pude cancelar la activación de <device(s)>.
  • cancelTooLate : Lo sentimos, ya es demasiado tarde para cancelar. En su lugar, usa <device(s)> o la app.
  • channelSwitchFailed : No se pudo cambiar al canal <channel name>. Vuelve a intentarlo más tarde.
  • loaderIssue : Lo sentimos, parece que hay <device(s)> <has/have> <a cargador issue/charger issues>.
  • commandInsertFailed : No se pueden procesar comandos para <device(s)>.
  • deadBattery : <device(s)> <has/have> <agüento batería/baterías>.
  • degreesOutOfRange : Los grados solicitados están fuera del rango de <device(s)>.
  • deviceAlertNeedsAssistance : <device(s)> <has/have> una alerta activa y <need(s)> tu asistencia.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <anext temperaturas/extreme temperaturas>.
  • deviceBusy : Lo siento, parece que <device(s)> ya está realizando una acción.
  • deviceLoading : Lo siento, parece que <device(s)> no puede realizar esa acción porque (ha_shared.ItsItre size=$item.devices.total_device_count) se está cargando.
  • deviceClogged : Lo siento, parece que <device(s)> está obstruido.
  • deviceCurrentlyDispensing : <device(s)> ya está expendiendo algo en este momento.
  • deviceDoorOpen : La puerta está abierta en <device(s)>. Ciérrala y vuelve a intentarlo.
  • deviceHandleClosed : El identificador se cerró en <device(s)>. Ábrelo y vuelve a intentarlo.
  • deviceJammingDetected : <device(s)> <is/are> jamed.
  • deviceLidOpen : La tapa está abierta en <device(s)>. Ciérrala y vuelve a intentarlo.
  • deviceNeedsRepair : <device(s)> <need(s)> que se repararán. Comunícate con tu proveedor de servicios local.
  • deviceNotDocked : Lo sentimos, parece que <device(s)> <isn't/aren't> está en un conector. Conecta <it/them> y vuelve a intentarlo.
  • deviceNotFound : <device(s)> <is/are>n't available. Intenta volver a configurar <it/them>.
  • deviceNotMounted : Lo siento, parece que <device(s)> no puede hacerlo porque <it/they> <is/are>no está activado.
  • deviceNotReady : <device(s)> <is/are>n't ready.
  • deviceStuck : <device(s)> <is/are> está atascado y necesita tu ayuda.
  • deviceTampered : Se manipuló <device(s)> <has/have>.
  • deviceThermalShutdown : Lo sentimos, parece que <device(s)> se apagó debido a las temperaturas extremas.
  • directResponseOnlyUnreachable : <device(s)> <not/t/don't> support remote.
  • disarmFailure : <device(s)> no se pudo desactivar.
  • discreteOnlyOpenClose : Lamentablemente, <device(s)> solo se puede abrir o cerrar por completo.
  • dispenseAmountAboveLimit : <device(s)> no puede expender tanta cantidad.
  • dispenseAmountBelowLimit : <device(s)> no puede expender tan poca cantidad.
  • dispenseAmountRemainingExceeded : <device(s)> no tiene suficiente <dispense item> para hacerlo.
  • dispenseFractionalAmountNotSupported : <device(s)> no puede expender fracciones de <dispense item>.
  • dispenseFractionalUnitNotSupported : <device(s)> no admite fracciones de esa unidad para <dispense item>.
  • dispenseUnitNotSupported : <device(s)> no admite esa unidad para <dispense item>.
  • puertaClosedTooLong : Hace tiempo que no se abre la puerta de <device(s)>. Abre la puerta, asegúrate de que haya algo dentro y vuelve a intentarlo.
  • EmergencyHeatOn : <device(s)> <is/are> está en modo calefactor de emergencia, por lo que <it/they>deberá ajustarse manualmente.
  • FallyBattery : <device(s)> <has/have> <a baterías defectuosas>.
  • floorUnreachable : <device(s)> no puede acceder a esa habitación. Mueve <it/them> al piso correcto y vuelve a intentarlo.
  • functionNotSupported : En realidad, <device(s)> <not/t/t> no admite esa funcionalidad.
  • genericDispenseNotSupported : Necesito saber qué quieres dispensar. Vuelve a intentarlo con el nombre del elemento.
  • hardError : Se produjo un error y no puedo controlar el dispositivo del hogar.
  • hardError : Se produjo un error y no puedo controlar el dispositivo del hogar.
  • inAutoMode : <device(s)> <is/are> actualmente en modo automático. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inAwayMode : <device(s)> <is/are> está configurado en el modo Ausente. Para controlar el termostato, debes cambiarlo manualmente al modo En casa con la app de Nest desde un teléfono celular, tablet o computadora.
  • inDryMode : <device(s)> <is/are> actualmente en modo seco. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inEcoMode : <device(s)> <is/are> está en este modo. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inFanOnlyMode : <device(s)> <is/are> está configurado en el modo de solo ventilador. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inHeatOrCool : <dispositivos/> <is/no>están en modo frío/calor.
  • inHumidifierMode : <dispositivo(s)> <is/are> está configurado en el modo humidificador. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inOffMode : <device(s)> <is/are> está desactivado actualmente. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inPurifierMode : <device(s)> <is/are> actualmente en modo de purificador. Para cambiar la temperatura, deberás usar <it/them> para cambiar a otro modo.
  • inSleepMode : <device(s)> <is/are> en modo de suspensión. Vuelve a intentarlo más tarde.
  • en SoftwareUpdate : <device/s>> <is/are> se encuentra en una actualización de software.
  • lockFailure : No se pudieron bloquear <device(s)>.
  • blockState : <device(s)> <is/are> bloqueado actualmente.
  • LockToRange : Esa temperatura está fuera del rango bloqueado en <device(s)>.
  • lowBattery : <device(s)> <has/have> batería baja.
  • maxSettingReached : <device(s)> <is/are> ya se estableció en la configuración más alta.
  • maxSpeedReached : <device(s)> <is/are> ya se estableció con la velocidad máxima.
  • minSettingReached : <device(s)> <is/are> ya se estableció en la configuración más baja.
  • minSpeedReached : <device(s)> <is/are> ya se estableció con la velocidad mínima.
  • monitoringServiceConnectionLost : <device(s)> <has/have> perdió <its/su> conexión con el servicio de supervisión.
  • NeedAttachment : Lo sentimos, pero parece que <device(s)> <is/are> no cuenta con un archivo adjunto obligatorio. Reemplázala y vuelve a intentarlo.
  • needBin : Lo sentimos, parece que <device/s> <is/are> no tiene un contenedor. Reemplázala y vuelve a intentarlo.
  • NeedPads : <device(s)> <need(s)> nuevas almohadillas.
  • NeedSoftwareUpdate : <device(s)> <need(s)> una actualización de software.
  • NeedWater : <device(s)> <need(s)> agua
  • networkProfileNotRecognized : Lo siento, no reconozco "<network profile>" en <device(s)>.
  • networkSpeedTestInProgress : Ya estoy probando el proceso <network> <speed/speeds>>.
  • noAvailableApp : Lo siento, parece que <app name> no está disponible.
  • noAvailableChannel : Lo siento, parece que el canal <channel name> no está disponible.
  • noChannelSubscription : Lo sentimos, no estás suscrito al canal <channel name> en este momento.
  • noTimerExists : Lo siento, parece que no se estableció ningún temporizador en <device(s)>.
  • notSupported : Lamentablemente, ese modo no está disponible en <device(s)>.
  • obstruDetected : los <device(s)> detectaron una obstrucción.
  • sin conexión , deviceOffline : Lo sentimos, parece que hay <device/s> > <is/are>no están disponibles en este momento.
  • onRequiresMode : Especifica el modo que quieres activar.
  • phraseIncorrect : Lamentablemente, parece que el PIN es incorrecto.
  • percentOutOfRange : Lo siento, no puedo establecer <device(s)> en <percent>.
  • pinIncorrecto : (passphraseIncorrecto)
  • rainDetected : No abrí <device(s)> porque se detectó lluvia.
  • rangeTooClose : Esos son demasiado próximos para establecer un intervalo frío/calor en los <device(s)>. Elige temperaturas más distantes.
  • relinkRequired : Se produjo un error con tu cuenta. Usa la app de Google Home o la del Asistente para volver a vincular <device(s)>.
  • remoteSetDisabled :
    • Parámetro opcional errorCodeReason
    • currentlyArmed : Como la seguridad ya está activada, debes usar <device(s)> o la app para realizar cualquier cambio.
    • remoteUnlockNotAllowed - Lo siento, no puedo desbloquear <device(s)> de forma remota.
    • remoteControlOff: Esa acción está inhabilitada actualmente. Habilita el control remoto en los <device(s)> y vuelve a intentarlo.
    • childSafetyModeActive: Esa acción está inhabilitada para <device(s)> mientras el modo de seguridad infantil está activo.
  • roomOnDifferentFloors : <device(s)> no puede llegar a esas habitaciones porque se encuentran en diferentes pisos.
  • securityShutOff : <device(s)> <is/are> en el modo de apagado seguro, por lo que <it/they>tendrá que ajustarse manualmente.
  • SceneCannotBeApplied : No se pueden aplicar <device(s)>.
  • securityRestriction : <device(s)> <has/have> una restricción de seguridad.
  • softwareUpdateNotAvailable : No hay ninguna actualización de software disponible en <device(s)>.
  • startRequiresTime : Para ello, deberás indicar por cuánto tiempo quieres ejecutar <device(s)>.
  • tillCoolingDown : <device(s)> <is/are> still enfriamiento.
  • tillWarmingUp : <device(s)> <is/are> still Warming.
  • StreamUnavailable : Lamentablemente, parece que la transmisión no está disponible desde <device(s)>.
  • streamUnplayable : En este momento, no puedo reproducir contenido en <device(s)>.
  • tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Completa <it/them> y vuelve a intentarlo.
  • targetAlreadyReached : Lamentablemente, parece que esa ya es la temperatura actual.
  • timerValueOutOfRange : <device(s)> no se puede establecer durante ese período.
  • tooManyFailedRetrys : Se produjeron demasiados intentos fallidos. Ve a la app de tu dispositivo para completar esa acción.
  • transientError : Se produjo un error al controlar <device(s)>. Vuelve a intentarlo.
  • OffOff , deviceTurnedOff : <device(s)> <is/are> está desactivado en este momento.
  • cannotToLocateDevice : No pude ubicar <device(s)>.
  • unknownFoodPreset : <device(s)> no admite ese ajuste predeterminado.
  • desbloqueoFailure : <device(s)> no se pudo desbloquear.
  • unpausableState : <device(s)> no se puede detener en este momento.
  • usuario cancelado : ok
  • valueOutOfRange : <device(s)> no se puede establecer en esa temperatura.

Excepciones

Debes mostrar una excepción cuando haya un problema o una alerta asociados con un comando. El comando podría tener éxito o fallar.

Si el comando se realizó de forma correcta (estado = "SUCCESS"), informa las excepciones con la característica StatusReport (para dispositivos que no sean el objetivo) o muestra un exceptionCode adecuado (para el dispositivo de destino).

Por ejemplo, si la pantalla de lint de la secadora está llena, el usuario aún puede iniciar su secadora, pero tal vez quieras advertirle sobre este estado. Del mismo modo, cuando un dispositivo tiene poca batería que no está vacía, puedes ejecutar un comando de todas formas, pero debes informarle que la batería está baja.

Si el comando falla debido a excepciones, el estado debe ser "EXCEPTIONS", y las excepciones deben informarse con la característica StatusReport.

Excepción sin bloqueo (SUCCESS) sobre el dispositivo de destino

Este ejemplo es para trabar la puerta:

La cerradura de la puerta principal tiene poca batería. Trabando la puerta principal

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

Excepción sin bloqueo (SUCCESS) sobre otro dispositivo mediante StatusReport

Este ejemplo es para activar un sistema de seguridad: Bien, se activará el sistema de seguridad. La ventana frontal está abierta.

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

Excepción de bloqueo sobre otro dispositivo con 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"
          }
        ]
      }
    }
  }
}

Lista de excepciones

Las siguientes excepciones producirán el TTS asociado en el dispositivo.

  • bagFull : <device(s)> <has/have> <a full bag/full Bag>.. Vacía <it/them> y vuelve a intentarlo.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carboncarbonoxideDetected : se detectó monóxido de carbono en <house name>.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <anext temperaturas/extreme temperaturas>.
  • deviceJammingDetected : <device(s)> <is/are> jamed.
  • deviceMoved : <device(s)> <was/were> movidos.
  • deviceOpen : <device(s)> <is/are> open.
  • deviceTampered : Se manipuló <device(s)> <has/have>.
  • deviceUnplugged : <device(s)> <is/are> unplugged.
  • floorUnreachable : <device(s)> no puede acceder a esa habitación. Mueve <it/them> al piso correcto y vuelve a intentarlo.
  • hardwareFailure : <device(s)> <has/have> un problema de hardware.
  • en SoftwareUpdate : <device/s>> <is/are> se encuentra en una actualización de software.
  • isBypassed : <device(s)> <is/are> actualmente se omite.
  • lowBattery : <device(s)> <has/have> batería baja.
  • motionDetected : Movimiento <device(s)> <detect(s)>.
  • NeedPads : <device(s)> <need(s)> nuevas almohadillas.
  • NeedSoftwareUpdate : <device(s)> <need(s)> una actualización de software.
  • NeedWater : <device(s)> <need(s)> agua
  • networkJammingDetected : La conexión de red doméstica a <device(s)> no funciona correctamente.
  • noIssuesReported : <device(s)> no informó ningún problema.
  • roomOnDifferentFloors : <device(s)> no puede llegar a esas habitaciones porque se encuentran en diferentes pisos.
  • runCycleFinished : <device(s)> <has/have> terminó de ejecutarse.
  • securityRestriction : <device(s)> <has/have> una restricción de seguridad.
  • humoDetected : Se detectó humo en <house name>.
  • tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Completa <it/them> y vuelve a intentarlo.
  • CellularBackup : <device(s)> <is/are> using mobile backup.
  • WaterLeakDetected : <device(s)> <detect(s)> una fuga de agua.