Erros e exceções

Este documento lista os erros e exceções oficialmente compatíveis com dispositivos de casa inteligente. Use esses códigos de erros e exceções na resposta da intent ou em notificações se você a tiver implementado. Assim, o Google Assistente alerta 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 aos usuários, por exemplo, "Desculpe, device não está disponível no momento".

Erros

Retorne um código de erro quando um problema fizer com que uma solicitação de execução ou de 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 no nível global. Por exemplo, se um usuário tiver muitas luzes de um provedor e for controlado por um hub, quando ele solicitar a desativação de todas as luzes, o provedor poderá retornar um erro no nível do dispositivo se uma única luz estiver off-line ou um erro 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 erros no nível global ou no nível do dispositivo. Quando um dispositivo estiver off-line, você precisará informar o estado {"online": false} no reportState, mesmo que retorne o código do erro deviceOffline.

Resumindo:

• Erro global: todos os dispositivos na resposta têm o mesmo erro
• Erro no nível local: resposta mista com erros e casos de 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 de erro de nível global deviceOffline devido ao hub está off-line:

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

Um exemplo de 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 nível do dispositivo

Resposta QUERY

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

EXECUTAR resposta

O snippet JSON a seguir mostra como retornar erros no nível do dispositivo na resposta EXECUTAR.

{
  "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 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 produzirão o TTS associado no dispositivo.

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 for bem-sucedido (status = "SUCCESS"), informe as 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 do lint estiver totalmente cheia, o usuário ainda poderá iniciar o secador, mas talvez você queira avisá-lo sobre esse estado. Da mesma forma, quando um dispositivo tem uma bateria fraca que não está vazia, você ainda pode executar um comando, mas precisa informar que a bateria está fraca.

Se o comando falhar devido a exceções, o status será "EXCEPTIONS" e as exceções precisarão ser relatadas 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á 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 (SUCCESS) em outro dispositivo usando o 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"
        }]
      }
    }]
  }
}

Bloquear a exceção 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.