Errores y excepciones

En este documento, se enumeran los errores y las excepciones oficialmente compatibles para dispositivos de casa inteligente. Usa estos códigos de errores y excepciones en la respuesta del intent o en las notificaciones si lo implementaste, de modo que Asistente de Google alerte a los usuarios finales sobre problemas relacionados con un comando o el estado del 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, dispositivo no está disponible en este momento".

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 se bloquea una puerta 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 conectar a nivel del dispositivo o a nivel global. Por ejemplo, si un usuario tiene muchas luces de un proveedor y la controla un concentrador, cuando el usuario solicite 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 de nivel global si todo el concentrador está sin conexión y no se pueden controlar las luces. 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.

Resumen:

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

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 del error de nivel global deviceOffline debido al concentrador no tiene conexión:

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

Se está actualizando un ejemplo de error inSoftwareUpdate a nivel global 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"
      }
    }
  }
}

EJECUTAR respuesta

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

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

Excepciones

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

Si el comando se ejecuta 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 la secadora, pero tal vez quieras advertirle sobre este estado. De manera similar, cuando un dispositivo tiene poca batería vacía, puedes ejecutar un comando de todos modos, pero debes avisarle que queda poca.

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 con StatusReport

Este ejemplo es para activar un sistema de seguridad: Bien, 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 el TTS asociado al dispositivo.