Erros e exceções

Este documento lista os erros e exceções oficialmente compatíveis com dispositivos de casa inteligente. Use esses erros e códigos de exceção na resposta da intent ou nas notificações (link em inglês), se você as tiver implementado. Dessa forma, o Google Assistente alerta os usuários finais sobre problemas relacionados a um determinado comando ou estado do dispositivo. Se a resposta tiver formatação incorreta ou errorCode, o Google Assistente mostrará ao usuário uma mensagem de erro genérica, por exemplo, "O device não está disponível no momento".

Erros

Você precisará retornar um código de erro quando um problema fizer com que uma solicitação de execução ou consulta falhe. Por exemplo, se uma fechadura estiver emperrada e não puder ser trancada ou destrancada, um erro sobre esse estado será retornado ao usuário.

Os códigos de erro podem ser anexados no nível do dispositivo ou global. Por exemplo, se um usuário tiver muitas luzes de um provedor e for controlado por um hub, quando o usuário pedir para apagar todas as luzes, o provedor poderá retornar um erro no nível do dispositivo se uma única luz estiver off-line ou um erro de nível global se todo o hub estiver off-line e nenhuma luz puder ser controlada. Se todos os dispositivos estiverem off-line, não haverá diferença entre usar erros de nível global ou de dispositivo. Quando um dispositivo está off-line, é necessário informar o estado {"online": false} em reportState mesmo que você retorne o código de erro deviceOffline.

Resumindo:

• Erro de nível global: todos os dispositivos na resposta têm o mesmo erro
• Erro no nível local: resposta mista com casos de erro e sucesso

Erros de nível global

O snippet JSON a seguir mostra como retornar erros de nível global na resposta QUERY ou EXECUTE.

Um exemplo do erro de nível global deviceOffline porque o hub está off-line:

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

Um exemplo do erro de nível global inSoftwareUpdate devido ao hub está sendo atualizado:

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

Erros no dispositivo

Resposta de QUERY

O snippet JSON abaixo mostra como retornar erros no nível do dispositivo na resposta da QUERY.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

EXECUTAR resposta

O snippet JSON abaixo mostra como retornar erros no nível do dispositivo na resposta 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
        }
      }
    ]
  }
}

Notificações com erros

Notificação proativa

O snippet JSON a seguir mostra como informar erros no nível do dispositivo em uma notificação proativa.

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

Resposta de acompanhamento

O snippet JSON a seguir mostra como informar erros no dispositivo em uma resposta de acompanhamento.

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

Os erros a seguir produzirão o TTS associado no dispositivo.

Exceções

Você precisará retornar uma exceção quando houver um problema ou alerta associado a um comando. O comando pode funcionar ou falhar.

Se o comando tiver sido bem-sucedido (status = "SUCCESS"), informe exceções usando a característica StatusReport (para dispositivos diferentes do destino) ou retornando um exceptionCode apropriado (para o dispositivo de destino).

Por exemplo, se a tela de lint da secadora estiver cheia, o usuário ainda poderá iniciar a secadora, mas talvez você queira avisar sobre esse estado. Da mesma forma, quando um dispositivo tem a bateria fraca que não está descarregada, ainda é possível executar um comando, mas é necessário informar que a bateria do dispositivo está baixa.

Se o comando falhar devido a exceções, o status vai ser "EXCEPTIONS", e as exceções precisam ser informadas usando a característica StatusReport.

Exceção sem bloqueio (SUCCESS) no dispositivo de destino

Este exemplo é para trancar a porta:

A trava da porta da frente está com a bateria fraca. Trancando a porta da frente.

{
  "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"
      }
    }]
  }
}

Exceção sem bloqueio (SUCESSO) sobre outro dispositivo que usa StatusReport

Este exemplo é para ligar um sistema de segurança: Ok, ligando o sistema de segurança. A janela da frente está aberta.

{
  "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"
        }]
      }
    }]
  }
}

Exceção de bloqueio sobre outro dispositivo usando o 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 exceções

As exceções a seguir produzirão o TTS associado no dispositivo.