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 oficiales para dispositivos del hogar inteligente. Usa estos errores y códigos de excepción específicos en la respuesta del intent o en las notificaciones, si lo implementaste, para que Asistente de Google alerte a los usuarios finales sobre problemas relacionados con un comando o estado del dispositivo determinado. Si la respuesta contiene un formato incorrecto o errorCode, Asistente de Google muestra un mensaje de error genérico, por ejemplo, "Lo siento, device is not available now now".

Errores

Deberías 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 bloquear o desbloquear, se debe mostrar al usuario un error relacionado con 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 se controla con un concentrador, cuando el usuario solicita apagar todas las luces, el proveedor puede mostrar un error a nivel del dispositivo si una sola luz está sin conexión o un error a nivel global si todo el centro 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 a nivel del dispositivo. Cuando un dispositivo está sin 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 de nivel global: todos los dispositivos en la respuesta tienen el mismo error
  • Error a nivel local: respuesta mixta con errores y casos de éxito

Errores a nivel global

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

Un ejemplo del error de nivel global deviceOffline debido al centro está sin conexión:

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

Se está actualizando un ejemplo del error de nivel global inSoftwareUpdate debido al concentrador:

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

Errores a nivel del dispositivo

Respuesta de QUERY

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 EJECUTAR

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 de 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.

  • aboveMaximumLightEffectsDuration : Eso supera la duración máxima de 1 hora. Vuelve a intentarlo.
  • aboveMaximumTimerDuration : Solo puedo establecer <device(s)> por hasta <time period>
  • actionNotAvailable : Lo siento, parece que no puedo hacer eso en este momento.
  • actionUnavailable whileRunning : <device(s)> <is/are> se está ejecutando, por lo que no puedo hacer cambios.
  • armArmed : <device(s)> <is/are> ya está activado.
  • ya AtMax : <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)> <está/está> desactivado.
  • yaDocked : <device(s)> <is/are> already conector.
  • ya existente: <device(s)> <is/are> already in that state.
  • alreadyLocked : <device(s)> <is/are> already blocked.
  • ya desactivado: <device(s)> <is/are> already off.
  • ya está activada : <device(s)> <is/are> already on.
  • openOpen : <device(s)> <is/are> already open.
  • alreadyPaused : <device(s)> <is/are> already already.
  • alreadyStart : <device(s)> <is/are> already started.
  • Ya está detenida : <dispositivo(s)> <is/are> ya se detuvo.
  • ya desbloqueado: <device(s)> <is/are> already desbloqueado.
  • ambiguousZoneName : Lo sentimos, <device(s)> no puede identificar a qué zona te refieres. Asegúrate de que las zonas tengan nombres únicos y vuelve a intentarlo.
  • amountAboveLimit: Eso es más de lo que admite <device(s)>.
  • appLaunchFailed : No se pudo iniciar <app name> en <device(s)>.
  • armFailure : <device(s)> no se pudo activar.
  • armLevelNeeded : No sé a qué nivel configurar <device(s)>. Di "Establecer <dispositivo(s)> en <baja seguridad>" o "Configurar <dispositivo(s)> en <alta seguridad>"
  • authFailure : No puedo establecer conexión con <device(s)>. Intenta verificar que la <device/devices> <is/are> esté completamente configurada.
  • bagFull : <device(s)> <has/have> <a full bag/full bolsos>. Vacía <it/them> y vuelve a intentarlo.
  • belowMinimumLightEffectsDuration : Inferior a la duración mínima de 5 minutos. Vuelve a intentarlo.
  • belowMinimumTimerDuration : No puedo configurar <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 siento, ya es demasiado tarde para cancelar. En su lugar, usa <device(s)> o la app.
  • channelSwitchFailed : No se pudo cambiar al canal <nombre del canal>. Vuelve a intentarlo más tarde.
  • cargadorIssue : Lo sentimos, parece que hay <device(s)> <has/have> <a cargador issue/charger issues>.
  • commandInsertFailed : No se pueden procesar los comandos para <device(s)>.
  • deadBattery : <device(s)> <has/have> <a muertos/baterías>.
  • gradosOutOfRange : 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)> <es/está> a <una temperatura extrema/temperaturas extremas>.
  • deviceBusy : Lo siento, parece que <device(s)> ya está haciendo una acción en este momento.
  • deviceCharging : Lo siento, parece que <device(s)> no puede hacer eso 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 controlador está cerrado en <device(s)>. Ábrelo y vuelve a intentarlo.
  • deviceJammingDetected : <device(s)> <is/are> atascado.
  • 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/aren't> está anclado. Conecta <it/them> y vuelve a intentarlo.
  • deviceNotFound : <device(s)> <is/are>n't available. Intenta volver a configurar <it/them> de nuevo.
  • deviceNotMounted : Lo siento, parece que <device(s)> no puede hacer eso porque <it/they> <is/are>no está activado.
  • deviceNotReady : <device(s)> <is/are>n't ready.
  • deviceStuck : <device(s)> <is/are> se detuvo y necesita tu ayuda.
  • deviceTampered : Se manipuló <device(s)> <has/have>.
  • deviceThermalShutdown : Lo sentimos, parece que <device(s)> se apagó por temperaturas extremas.
  • directResponseOnlyUnreachable : <device(s)> <no admite/no> el control remoto.
  • dearmFailure : <device(s)> no se pudo desactivar.
  • discreteOnlyOpenClose : Los dispositivos <device(s)> solo se pueden abrir o cerrar por completo.
  • dispenseAmountAboveLimit: <device(s)> no puede expender tanta cantidad.
  • dispenseAmountUnderLimit: <device(s)> no puede distribuir una cantidad tan pequeña.
  • dispenseAmountRemainingExceeded : <device(s)> no tiene suficiente <dispense item> para hacerlo.
  • dispenseFractionalAmountNotSupported : <device(s)> no puede distribuir 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.
  • emergenciaHeatOn : <device(s)> <is/are> in Emergency Heat Mode, por lo que <it/they>deberá ajustarse manualmente.
  • FallyBattery : <device(s)> <has/have> <a una batería con fallas/baterías dañadas>.
  • 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)> <no admite/no> admite esa funcionalidad.
  • GenericDispenseNotSupported : Necesito saber lo que deseas 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> está actualmente configurado en modo automático. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inAwayMode : <device(s)> <is/are> está actualmente en modo Ausente. Para controlar el termostato, deberás cambiarlo manualmente al modo En casa con la app de Nest desde un teléfono, una tablet o una computadora.
  • inDryMode : <device(s)> <is/are> se estableció en modo seco. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inEcoMode : <device(s)> <is/are> se estableció en el modo Eco. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inFanOnlyMode : <device(s)> <is/are> está configurado en el modo solo ventilador. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inHeatOrCool : <device(s)> <is/are>n't in calor/frío.
  • inHumidifierMode : <device(s)> <is/are> se estableció en el modo humidificador. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inOffMode : <device(s)> <is/are> está desactivado. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inPurifierMode : <device(s)> <is/are> se estableció en modo de purificador. Para cambiar la temperatura, deberás usar <it/them> en otro modo.
  • inSleepMode : <device(s)> <is/are> en modo de suspensión. Vuelve a intentarlo más tarde.
  • inSoftwareUpdate : <device(s)> <is/are> se encuentra en una actualización de software.
  • lockFailure : <device(s)> no se pudo bloquear.
  • lockState : <device(s)> <is/are> bloqueado actualmente.
  • lockToRange : Esa temperatura está fuera del rango bloqueado en <device(s)>.
  • batería baja : <device(s)> <has/have> con batería baja.
  • maxSettingReached: <device(s)> <is/are> ya está establecido en la configuración más alta.
  • maxSpeedReached: <device(s)> <is/are> ya está configurado 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 está configurado en la velocidad mínima.
  • MonitoringServiceConnectionLost : <device(s)> <has/have> perdió <su/su> conexión al servicio de supervisión.
  • needs : Lo sentimos, pero parece que <device(s)> <is/are> no tiene 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)> nuevo.
  • 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 <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 hay ningún temporizador establecido en <device(s)>.
  • notSupported : Lamentablemente, ese modo no está disponible para <device(s)>.
  • obsionDetected : <device(s)> detectó una obstrucción.
  • sin conexión , deviceOffline : Lo sentimos, parece que <device(s)> <is/are>n no está disponible en este momento.
  • onRequiresMode: Especifica qué modo deseas activar.
  • passwordIncorrect : Lamentablemente, parece que el PIN es incorrecto.
  • percentOutOfRange : Lo siento, no puedo establecer <device(s)> en <percent>.
  • pinIncorrect : (passphraseIncorrect)
  • RainDetected : No abrí <device(s)> porque se detectó lluvia.
  • rangeTooClose : Estos valores son demasiado próximos para un intervalo Calor/Frío en <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 cambios.
    • remoteUnlockNotAllowed - No puedo desbloquear <device(s)> de forma remota.
    • remoteControlOff: La acción está inhabilitada actualmente. Habilita el control remoto en <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 están en pisos diferentes.
  • securityShutOff : <device(s)> <is/are> en el modo de apagado seguro, por lo que <it/they>deberá 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 hacerlo, deberás decirme por cuánto tiempo quieres ejecutar <device(s)>.
  • quietCoolingDown : <device(s)> <is/are> still cooling.
  • tillWarmingUp : <device(s)> <is/are> still Warming.
  • StreamUnavailable: Lamentablemente, parece que la transmisión no está disponible en <device(s)>.
  • stream unplayable: En este momento, no puedo reproducir la transmisión desde <device(s)>.
  • tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Llena <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.
  • tooManyFailedAttempts : 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.
  • TurnOff , deviceTurnedOff : <device(s)> <is/are> ahora están desactivados.
  • cannotToLocateDevice : No pude encontrar <device(s)>.
  • unknownFoodPreset: <device(s)> no admite ese ajuste predeterminado.
  • UnlockFailure : <device(s)> no se pudo desbloquear.
  • unpausableState : <device(s)> no se pueden pausar en este momento.
  • usuario cancelado : ok
  • valueOutOfRange : <device(s)> no se puede establecer en esa temperatura.

Excepciones

Deberías mostrar una excepción cuando haya un problema o una alerta asociada con un comando. El comando puede completarse con éxito o fallar.

Si el comando se realizó de forma correcta (estado = "SUCCESS"), informa 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 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 una batería baja que no está vacía, puedes ejecutar un comando, pero debes avisarle 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 que usa StatusReport

Este ejemplo es para activar un sistema de seguridad: Está 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"
        }]
      }
    }]
  }
}

Bloqueo de excepción 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 bolsos>. Vacía <it/them> y vuelve a intentarlo.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carbonMonoxideDetected: Se detectó monóxido de carbono en <house name>.
  • deviceAtExtremeTemperature : <device(s)> <es/está> a <una temperatura extrema/temperaturas extremas>.
  • deviceJammingDetected : <device(s)> <is/are> atascado.
  • deviceMoved : <device(s)> <fue/se movieron>.
  • deviceOpen : <device(s)> <is/are> abierto.
  • 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> tiene un problema de hardware.
  • inSoftwareUpdate : <device(s)> <is/are> se encuentra en una actualización de software.
  • isBypassed: <device/s>> <is/are> se omite.
  • batería baja : <device(s)> <has/have> con batería baja.
  • movimientoDetected : Movimiento <device(s)> <detect(s)>.
  • NeedPads : <device(s)> <need(s)> nuevo.
  • 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 están en pisos diferentes.
  • runCycleFinished : <device(s)> <has/have> ha terminado 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>. Llena <it/them> y vuelve a intentarlo.
  • Uso del respaldo celular : <dispositivo(s)> <is/are> está usando el respaldo celular.
  • waterLeakDetected: <device(s)> <detect(s)> es una fuga de agua.