Errores y excepciones

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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 los implementaste, de modo 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 les muestra a los usuarios un mensaje de error genérico, por ejemplo, "Lo sentimos, el dispositivo no está disponible en este momento".

Errores

Debes 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á 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 luces de un proveedor y estas están controladas por 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 a 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 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 deviceOffline a nivel global debido a que el concentrador está fuera de línea:

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

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 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 puede iniciarla, pero te recomendamos que le adviertas 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 informarles 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. Trabar 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"
        }]
      }
    }]
  }
}

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