Errores y excepciones

En este documento, se enumeran las excepciones y los errores admitidos 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 incorrecto, 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

Deberías mostrar un código de error cuando un problema cause que falle una solicitud de ejecución o consulta. Por ejemplo, si la cerradura de una puerta está atascada y no se puede trabar o destrabar, se debería 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 el estado {"online": false} en reportState, incluso si muestras el código de error deviceOffline.

Resumen:

• Error de nivel global: Todos los dispositivos de la respuesta tienen el mismo error.
• Error de nivel local: respuesta mixta con casos de éxito y errores

Errores a nivel global

En el siguiente fragmento de JSON, se muestra cómo mostrar errores de nivel global en la respuesta 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 del error de nivel global inSoftwareUpdate debido al 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 de JSON, se muestra cómo se muestran los 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 se muestran los 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 generará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 completarse con éxito o fallar.

Si el comando tuvo éxito (estado = "SUCCESS"), informa excepciones con la característica StatusReport (para dispositivos que no sean el de destino) o mostrando un exceptionCode adecuado (para el dispositivo de destino).

Por ejemplo, si la pantalla de lint de la secadora está llena, el usuario puede iniciar la secadora de todos modos, pero es posible que quieras advertirle 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 mediante la característica StatusReport.

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

Este ejemplo se usa 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 (ÉXITO) sobre otro dispositivo que usa StatusReport

Este ejemplo se usa para activar un sistema de seguridad: 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 generarán el TTS asociado en el dispositivo.