Errores y excepciones

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.

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.