Erros e exceções

Este documento lista os erros e as exceções com suporte oficial para dispositivos de casa inteligente. Use esses códigos de erros e exceções na resposta da intent ou nas notificações, se você as implementou, para que o Google Assistente alertem 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 vai mostrar aos usuários uma mensagem de erro genérica, por exemplo, "Desculpe, o dispositivo não está disponível no momento".

Erros

Você precisa retornar um código de erro quando um problema faz com que uma solicitação de execução ou de consulta falhe. Por exemplo, se uma fechadura de porta estiver travada e não puder ser travada ou destravada, 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 elas forem controladas por um hub, quando o usuário pedir para desligar todas as luzes, o provedor poderá retornar um erro no nível do dispositivo se uma única luz estiver off-line ou um erro no nível global se 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 no nível global ou no dispositivo.

Quando um dispositivo estiver off-line, informe {"online": false} para Report State em até 5 minutos após o comportamento do dispositivo.

Resumindo:

• Erro 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 no nível global

O snippet de JSON a seguir mostra como retornar erros globais em uma resposta QUERY ou EXECUTE.

Um exemplo de erro global deviceOffline devido ao hub está off-line:

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

Um exemplo de erro global inSoftwareUpdate devido à atualização do hub:

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

Erros no nível do dispositivo

Resposta de CONSULTA

O snippet JSON a seguir 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"
      }
    }
  }
}

Resposta EXECUTE

O snippet JSON a seguir 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 de 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 de JSON a seguir mostra como informar erros no nível do 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 vão produzir a TTS associada no dispositivo.

Exceções

Você precisa retornar uma exceção quando houver um problema ou alerta associado a um comando. O comando pode ser bem-sucedido ou falhar.

Se o comando tiver sido concluído (status = "SUCCESS"), informe as exceções usando o atributo StatusReport (para dispositivos diferentes do de destino) ou retornando um exceptionCode adequado (para o dispositivo de destino).

Por exemplo, se a tela de fiapos da secadora estiver cheia, o usuário ainda poderá ligar a secadora, mas você pode alertá-lo sobre esse estado. Da mesma forma, quando um dispositivo tem uma bateria fraca que não está vazia, ainda é possível executar um comando, mas é necessário informar que a bateria do dispositivo está fraca.

Se o comando falhar devido a exceções, o status será "EXCEPTIONS", e as exceções serão informadas usando o atributo StatusReport.

Exceção não de bloqueio (SUCESSO) sobre o dispositivo de destino

Este exemplo é para trancar a porta:

A fechadura 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 usando StatusReport

Este exemplo é para ativar um sistema de segurança: Ok, ativando 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 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 vão produzir a TTS associada no dispositivo.