Erros e exceções

Este documento lista os erros e as exceções oficialmente aceitos para dispositivos de casa inteligente. Use os códigos de erros e exceções fornecidos na resposta da intent ou nas notificações, se você as tiver implementado, para que o Google Assistente alerte os usuários finais sobre problemas relacionados a um determinado comando ou estado do dispositivo. Se a resposta tiver uma formatação incorreta ou errorCode, o Google Assistente vai mostrar uma mensagem de erro genérica, por exemplo, "O dispositivo não está disponível no momento".

Erros

Retorne um código do 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 precisa ser retornado ao usuário.

Os códigos do erro podem ser anexados no nível do dispositivo ou no nível 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 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 no nível global ou no nível do dispositivo.

Em resumo:

• 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 globais

O snippet JSON a seguir mostra como retornar erros globais na resposta QUERY ou EXECUTE.

Um exemplo de erro global deviceOffline devido ao hub estar 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 dispositivo

Resposta da CONSULTA

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

Relatórios de estado on-line e off-line

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

Exceções

Retorne 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 bem-sucedido (status = "SUCCESS"), informe as exceções usando o atributo StatusReport (para dispositivos que não sejam o de destino) ou retornando um exceptionCode apropriado (para o dispositivo de destino).

Por exemplo, se o filtro de fiapos da secadora estiver cheio, o usuário ainda poderá iniciar o aparelho, mas talvez você queira avisar sobre esse estado. Da mesma forma, quando um dispositivo está com bateria fraca, mas não descarregada, ainda é possível executar um comando, mas é preciso informar que a bateria 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 bloqueante (SUCCESS) sobre o dispositivo de destino

Este exemplo é para trancar a porta:

A fechadura da porta da frente está com as pilhas fracas. 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 (SUCCESS) 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 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 seguintes exceções vão produzir o TTS associado no dispositivo.