Erreurs et exceptions

Ce document répertorie les erreurs et les exceptions officiellement compatibles avec les appareils pour la maison connectée. Veuillez utiliser les codes d'erreurs et d'exceptions indiqués dans la réponse d'intent ou dans les notifications si vous l'avez implémentée afin que l'Assistant Google alerte les utilisateurs finaux en cas de problèmes liés à une commande ou à un état d'appareil donné. Si la réponse contient une mise en forme incorrecte ou errorCode, l'Assistant Google affiche un message d'erreur générique (par exemple, "Désolé, l'appareil n'est pas disponible pour le moment".

Erreurs

Vous devez renvoyer un code d'erreur lorsqu'un problème entraîne l'échec d'une requête d'exécution ou de requête. Par exemple, si un verrou de porte est coincé et ne peut pas être verrouillé ni déverrouillé, une erreur concernant cet état doit être renvoyée à l'utilisateur.

Les codes d'erreur peuvent être ajoutés au niveau de l'appareil ou au niveau global. Par exemple, si un utilisateur possède plusieurs ampoules provenant d'un seul fournisseur et qu'elles sont contrôlées par un hub, l'utilisateur peut renvoyer une erreur au niveau de l'appareil si l'un d'eux est hors connexion ou une erreur d'ordre général si l'intégralité de son hub est hors connexion et qu'aucun éclairage ne peut être contrôlé. Si tous les appareils sont hors connexion, il n'y a aucune différence entre l'utilisation d'erreurs à l'échelle globale ou au niveau de l'appareil. Lorsqu'un appareil est hors connexion, vous devez signaler l'état {"online": false} dans reportState, même si vous renvoyez le code d'erreur deviceOffline.

En résumé :

• Erreur globale: tous les appareils inclus dans la réponse ont la même erreur
• Erreur au niveau local: réponse mélangée avec erreurs et réussites

Erreurs au niveau global

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau global dans la réponse QUERY ou EXECUTE.

Exemple d'erreur globale deviceOffline en raison du hub hors connexion:

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

Un exemple d'erreur globale inSoftwareUpdate en raison du hub est en cours de mise à jour:

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

Erreurs au niveau de l'appareil

Réponse QUERY

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau de l'appareil dans la réponse QUERY.

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

Réponse EXECUTE

L'extrait de code JSON suivant montre comment renvoyer des erreurs au niveau de l'appareil dans la réponse 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
        }
      }
    ]
  }
}

Notifications avec erreurs

Notification proactive

L'extrait de code JSON suivant montre comment signaler les erreurs au niveau de l'appareil dans une notification proactive.

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

Réponse de suivi

L'extrait de code JSON suivant montre comment signaler les erreurs au niveau de l'appareil dans une réponse de suivi.

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

Liste d'erreurs

Les erreurs suivantes entraînent la synthèse vocale associée sur l'appareil.

Exceptions

Vous devez renvoyer une exception en cas de problème ou d'alerte associé à une commande. La commande peut réussir ou échouer.

Si la commande a réussi (état = "SUCCESS"), signalez les exceptions à l'aide de la caractéristique StatusReport (pour les appareils autres que la cible) ou en renvoyant une exceptionCode appropriée (pour l'appareil cible).

Par exemple, si l'écran de lint du sèche-linge est plein, l'utilisateur peut toujours démarrer son sèche-linge, mais vous pouvez le prévenir de cet état. De même, lorsqu'un appareil dispose d'une batterie faible qui n'est pas vide, vous pouvez toujours exécuter une commande.

Si la commande échoue en raison d'exceptions, l'état doit être "EXCEPTIONS", et les exceptions doivent être signalées à l'aide de la caractéristique StatusReport.

Exception non bloquante (SUCCESS) concernant l'appareil cible

Cet exemple permet de verrouiller la porte:

Les piles de la porte d'entrée sont faibles. Je verrouille la porte d'entrée.

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

Exception non bloquante (SUCCESS) concernant un autre appareil à l'aide de StatusReport

Cet exemple permet d'activer un système de sécurité: OK, activation du système de sécurité. La fenêtre principale est ouverte.

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

Blocage des exceptions sur un autre appareil à l'aide de 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"
          }
        ]
      }
    }
  }
}

Liste d'exceptions

Les exceptions suivantes entraînent la synthèse vocale associée sur l'appareil.