Errores y excepciones

En este documento, se enumeran los errores y las excepciones compatibles oficialmente para los dispositivos de casa inteligente. Usa estos códigos de errores y excepciones 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 determinados. Si la respuesta contiene errorCode o un formato incorrectos, Asistente de Google mostrará un mensaje de error genérico a los usuarios, por ejemplo, "Lo siento, device no está disponible en este momento".

Errores

Debes mostrar un código de error cuando un problema haga que falle una solicitud de ejecución o consulta. Por ejemplo, si la cerradura de una puerta está trabada y no se puede cerrar ni abrir, se debe mostrar un error sobre este estado al usuario.

Los códigos de error se pueden adjuntar a nivel del dispositivo o a nivel global. Por ejemplo, si un usuario tiene muchas lámparas de un proveedor y las controla un concentrador, cuando solicita que se apaguen 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 toda la unidad central está sin conexión y no se pueden controlar las luces. Si todos los dispositivos están sin conexión, no hay diferencia entre usar errores a nivel global o a nivel del dispositivo.

Cuando un dispositivo no tiene conexión, debes informar {"online": false} a Report State en un plazo de 5 minutos después de que se detecte el comportamiento del dispositivo.

Resumen:

  • Error a nivel global: Todos los dispositivos de 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 de JSON, se muestra cómo mostrar errores a nivel global en la respuesta de QUERY o EXECUTE.

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

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

Un ejemplo de error inSoftwareUpdate a nivel global debido a que el concentrador se está actualizando:

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

En el siguiente fragmento de JSON, se muestra cómo mostrar errores a nivel del dispositivo en la respuesta 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
        }
      }
    ]
  }
}

Notificaciones con errores

Notificación proactiva

En el siguiente fragmento de 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 de 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 la función de TTS asociada en el dispositivo.

  • aboveMaximumLightEffectsDuration : El valor es superior a 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 : Lo siento, no puedo hacer eso en este momento.
  • actionUnavailable whileRunning : <device(s)> <is/are> se está ejecutando actualmente, por lo que no puedo realizar cambios.
  • alreadyArmed : <device(s)> <is/are> already armed.
  • alreadyAtMax : <device(s)> <is/are> ya se estableció en la temperatura máxima.
  • alreadyAtMin : <device(s)> <está/están> ya configurados en la temperatura mínima.
  • alreadyClosed : <device(s)> <está/están> cerrado(s).
  • ya está desactivado : <dispositivo(s)> <está/está> desactivado.
  • alreadyDocked : <device(s)> <is/are> already docked.
  • alreadyInState : <device(s)> <está/están> ya en ese estado.
  • 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> ya está abierto.
  • alreadyPaused : <device(s)> <is/are> already paused.
  • alreadyStarted : <device(s)> <is/are> already started.
  • alreadyStopped : <device(s)> <is/are> ya se detuvo.
  • alreadyUnlocked : <device(s)> <is/are> already unlocked.
  • 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 : Esa cantidad supera lo que pueden admitir los <device(s)>.
  • appLaunchFailed : Lo sentimos, no se pudo iniciar <nombre de la app> en <dispositivo(s)>.
  • armFailure : No se pudo activar <device(s)>.
  • armLevelNeeded : No sé bien a qué nivel establecer <device(s)>. Di "Establecer <dispositivos> en <seguridad baja>" o "Establecer <dispositivos> en <seguridad alta>".
  • authFailure : No puedo comunicarme con <device(s)>. Verifica la app para asegurarte de que <device/devices> <is/are> completamente configurados.
  • bagFull : <device(s)> <has/have> <a full bag/full bags>. Vacía <it/them> y vuelve a intentarlo.
  • belowMinimumLightEffectsDuration : El valor es inferior a la duración mínima de 5 minutos. Vuelve a intentarlo.
  • underMinimumTimerDuration : 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 el armado de <dispositivos>.
  • cancelTooLate : Lo siento, ya es demasiado tarde para cancelar. En su lugar, usa <device(s)> o la app.
  • channelSwitchFailed : Lo sentimos, no se pudo cambiar al canal <channel name>. Vuelve a intentarlo más tarde.
  • chargerIssue : Lo siento, parece que <device(s)> <has/have> <a charger issue/charger issues>.
  • commandInsertFailed : No se pueden procesar los comandos de <device(s)>.
  • deadBattery : <device(s)> <has/have> <a dead battery/dead batteries>.
  • degreesOutOfRange : Los grados solicitados están fuera del rango de <device(s)>.
  • deviceAlertNeedsAssistance : <device(s)> <tiene/tiene> una alerta activa y <necesita> asistencia.
  • deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
  • deviceBusy : Lo siento, pero parece que <device(s)> ya está realizando una tarea en este momento.
  • deviceCharging : Lo sentimos, parece que <device(s)> no puede realizar esa acción porque se está cargando (ha_shared.ItsThatre size=$item.devices.total_device_count).
  • deviceClogged : Lo siento, pero parece que <device(s)> está tapado.
  • 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 control está cerrado en <device(s)>. Ábrelo y vuelve a intentarlo.
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceLidOpen : La tapa está abierta en <device(s)>. Ciérrala y vuelve a intentarlo.
  • deviceNeedsRepair : <device(s)> <need(s)> to be repaired. Comunícate con el proveedor de servicios local.
  • deviceNotDocked : Lo siento, pero parece que <device(s)> <isn't/aren't> docked. Conecta <el dispositivo> y vuelve a intentarlo.
  • deviceNotFound : <device(s)> <is/are>n't available. Te recomiendo que vuelvas a configurar <el dispositivo/los dispositivos>.
  • deviceNotMounted : Lo siento, parece que <device(s)> no puede hacer eso porque <it/they> <is/are>n't mounted.
  • deviceNotReady : <device(s)> <is/are>n't ready.
  • deviceStuck : <device(s)> <is/are> atascado y necesita tu ayuda.
  • deviceTampered : <deviceTampered> <se manipuló> <deviceTampered>.
  • deviceThermalShutdown : Lo siento, parece que <device(s)> se apagó debido a temperaturas extremas.
  • directResponseOnlyUnreachable : <device(s)> <no es compatible/no> con el control remoto.
  • disarmFailure : No se pudieron desarmar los <device(s)>.
  • discreteOnlyOpenClose : Lo sentimos, <device(s)> solo se puede abrir o cerrar por completo.
  • dispenseAmountAboveLimit : <device(s)> no puede dispensar una cantidad tan grande.
  • dispenseAmountSupportedLimit : <device(s)> no puede expender tan poca cantidad.
  • dispenseAmountRemainingExceeded : <device(s)> no tiene suficientes <dispense item> para hacerlo.
  • dispenseFractionalAmountNotSupported : <device(s)> no puede dispensar 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>.
  • portClosedTooLong : 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 el modo de calefactor de emergencia, por lo que <it/there> deberá ajustarse manualmente.
  • faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
  • floorUnreachable : <device(s)> no puede llegar a esa habitación. Muévelo al piso correcto y vuelve a intentarlo.
  • functionNotSupported : En realidad, <device(s)> <doesn't/don't> admiten esa funcionalidad.
  • genericDispenseNotSupported : Necesito saber qué te gustaría dispensar. Vuelve a intentarlo con el nombre del elemento.
  • hardError : Lo siento, se produjo un error y no puedo controlar el dispositivo de la casa.
  • hardError : Lo siento, se produjo un error y no puedo controlar el dispositivo de la casa.
  • inAutoMode : <device(s)> <is/are> está configurado actualmente en el modo automático. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inAwayMode : <device(s)> <está/están> configurados actualmente en modo ausente. Para controlar el termostato, debes 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> actualmente configurados en modo seco. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inEcoMode : <device(s)> <is/are> actualmente configurados en modo eco. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inFanOnlyMode : <device(s)> <is/are> actualmente configurados en modo solo ventilador. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
  • inHumidifierMode : <device(s)> <is/are> está configurado actualmente en el modo humidificador. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inOffMode : Los <dispositivos> están <desactivados>. Para cambiar la temperatura, deberás cambiarlos a otro modo.
  • inPurifierMode : <device(s)> <está/están> configurados actualmente en el modo purificador. Para cambiar la temperatura, deberás cambiar <el/los> a otro modo.
  • inSleepMode : <device(s)> <están> en modo de suspensión. Vuelve a intentarlo más tarde.
  • inSoftwareUpdate : <device(s)> <is/are> actualmente en una actualización de software.
  • lockFailure : No se pudo bloquear <device(s)>.
  • lockedState : <device(s)> <is/are> bloqueados actualmente.
  • blockToRange : Esa temperatura está fuera del rango bloqueado en <device(s)>.
  • lowBattery : <device(s)> <has/have> batería baja.
  • maxSettingReached : <device(s)> <is/are> ya está configurado en el parámetro de configuración más alto.
  • maxSpeedReached : <device(s)> <is/are> ya se estableció en la velocidad máxima.
  • minSettingReached : <device(s)> <is/are> ya está configurado en el parámetro de configuración más bajo.
  • minSpeedReached : <device(s)> <está/están> ya configurados en la velocidad mínima.
  • monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
  • needsAttachment : Lo siento, pero parece que al <device(s)> le falta un archivo adjunto obligatorio. Reemplázalo y vuelve a intentarlo.
  • needsBin : Lo siento, parece que al <device(s)> <is/are> le falta un contenedor. Reemplázalo y vuelve a intentarlo.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> una actualización de software.
  • needsWater : <device(s)> <need(s)> water.
  • networkProfileNotRecognized : Lo siento, no reconozco "<network profile>" en <device(s)>.
  • networkSpeedTestInProgress : Ya estoy probando la <network> <speed/speeds>>.
  • noAvailableApp : Lo siento, parece que <nombre de la app> no está disponible.
  • noAvailableChannel : Lo sentimos, 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)>.
  • no compatible : Lo sentimos, ese modo no está disponible para <device(s)>.
  • obstructionDetected : <device(s)> detectó una obstrucción.
  • offline , deviceOffline : Lo siento, parece que los <dispositivos> <están>n't disponibles en este momento.
  • onRequiresMode : Especifica qué modo quieres activar.
  • passphraseIncorrect : Lo siento, 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 están demasiado cerca para establecer un intervalo Calor • Frío para <device(s)>. Elige temperaturas más distantes.
  • relinkRequired : Lo sentimos, pero parece que se produjo un error con tu cuenta. Usa la app de Google Home o la de Asistente para volver a vincular <device(s)>.
  • remoteSetDisabled :
    • Parámetro opcional errorCodeReason
    • currentlyArmed: Lo siento, como ya se activó la protección, debes usar <device(s)> o la app para realizar cualquier cambio.
    • remoteUnlockNotAllowed: Lo siento, no puedo desbloquear los <dispositivos> de forma remota.
    • remoteControlOff: Esa acción está inhabilitada actualmente. Habilita el control remoto en <dispositivos> y vuelve a intentarlo.
    • childSafetyModeActive: Esa acción está inhabilitada para <device(s)> mientras el modo de seguridad para niños está activado.
  • roomsOnDifferentFloors : <device(s)> no puede llegar a esas habitaciones porque están en pisos diferentes.
  • safetyShutOff : <device(s)> <is/are> en modo de apagado seguro, por lo que <it/they> se deben ajustar manualmente.
  • sceneCannotBeApplied : Lo sentimos, no se pueden aplicar <device(s)>.
  • securityRestriction : <device(s)> <tiene> una restricción de seguridad.
  • softwareUpdateNotAvailable : Lo sentimos, no hay actualizaciones de software disponibles en <device(s)>.
  • startRequiresTime : Para ello, tendrás que decirme cuánto tiempo quieres que funcione <device(s)>.
  • stillCoolingDown : <device(s)> <is/are> still cooling down.
  • stillWarmingUp : <device(s)> <está/están> aún calentándose.
  • streamUnavailable : Lo sentimos, parece que la transmisión de <device(s)> no está disponible en este momento.
  • streamUnplayable : Lo siento, no puedo reproducir la transmisión desde <device(s)> en este momento.
  • tankEmpty : <dispositivo(s)> <tiene/tiene> <un tanque vacío/tanque vacío>. Llénalo <it/ellos> y vuelve a intentarlo.
  • targetAlreadyReached : Lo siento, parece que esa ya es la temperatura actual.
  • timeValueOutOfRange : No se puede establecer <device(s)> para ese período.
  • Too ManyFailedAttempts : Lamentablemente, se produjeron demasiados intentos fallidos. Para completar la acción, ve a la app de tu dispositivo.
  • transientError : Lo sentimos, se produjo un error al controlar <device(s)>. Vuelve a intentarlo.
  • turnedOff , deviceTurnedOff : <device(s)> <is/are> apagados en este momento.
  • unableToLocateDevice : No pude encontrar <device(s)>.
  • unknownFoodPreset : <device(s)> no admite ese ajuste predeterminado.
  • unlockFailure : No se pudieron desbloquear los <device(s)>.
  • unpausableState : No se puede pausar <device(s)> en este momento.
  • userCancelled : ok
  • valueOutOfRange : No se puede establecer <device(s)> en esa temperatura.

Excepciones

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

Si el comando se completó correctamente (estado = "SUCCESS"), informa las excepciones con el atributo StatusReport (para dispositivos que no sean el objetivo) o devuelve un exceptionCode adecuado (para el dispositivo de destino).

Por ejemplo, si la pantalla de pelusa de la secadora está llena, el usuario aún puede iniciarla, pero te recomendamos que le adviertas sobre este estado. De manera similar, cuando un dispositivo tiene una batería baja que no está vacía, puedes ejecutar un comando, pero debes informarle que la batería del dispositivo está baja.

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

Excepción no bloqueante (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 no bloqueante (SUCCESS) sobre otro dispositivo que usa StatusReport

Este ejemplo es para activar un sistema de seguridad: De acuerdo, activando 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 la función de TTS asociada en el dispositivo.

  • bagFull : <device(s)> <has/have> <a full bag/full bags>. 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 <nombre de la casa>.
  • 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 : Se <has/have> manipulado <device(s)>.
  • deviceUnplugged : <device(s)> <is/are> unplugged.
  • floorUnreachable : <device(s)> no puede llegar a esa habitación. Muévelo al piso correcto y vuelve a intentarlo.
  • hardwareFailure : <device(s)> <has/have> un problema de hardware.
  • inSoftwareUpdate : <device(s)> <is/are> en este momento en una actualización de software.
  • isBypassed : <device(s)> <is/are> actualmente omitidos.
  • lowBattery : <device(s)> <has/have> batería baja.
  • motionDetected : <device(s)> <detect(s)> motion.
  • needsPads : <device(s)> <need(s)> new pads.
  • needsSoftwareUpdate : <device(s)> <need(s)> una actualización de software.
  • needsWater : <device(s)> <need(s)> water.
  • 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 acceder a esas habitaciones porque están en pisos diferentes.
  • runCycleFinished : <device(s)> <has/have> finished running.
  • securityRestriction : <device(s)> <has/have> una restricción de seguridad.
  • humoDetected : Se detectó humo en <nombre de la casa>.
  • tankEmpty : <dispositivo(s)> <tiene/tiene> <un tanque vacío/tanque vacío>. Llénalo <it/ellos> y vuelve a intentarlo.
  • usingCellularBackup : <device(s)> <is/are> using cellular backup.
  • waterLeakDetected : <device(s)> <detect(s)> una fuga de agua.