Erreurs et exceptions

Ce document liste les erreurs et exceptions officiellement prises en charge pour les appareils de maison connectée. Veuillez utiliser ces codes d'erreur et d'exception dans la réponse d'intent ou dans les notifications si vous les avez implémentées afin que l'Assistant Google avertisse les utilisateurs finaux des problèmes liés à une commande ou à un état de l'appareil donnés. Si la réponse contient un formatage incorrect 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 une serrure de porte est bloquée et ne peut pas être verrouillée ni déverrouillée, une erreur concernant cet état doit être renvoyée à l'utilisateur.

Les codes d'erreur peuvent être associés au niveau de l'appareil ou de manière globale. Par exemple, si un utilisateur possède de nombreuses ampoules d'un même fournisseur et qu'elles sont contrôlées par un hub, lorsque l'utilisateur demande à éteindre toutes ses ampoules, le fournisseur peut renvoyer une erreur au niveau de l'appareil si une seule ampoule est hors connexion, ou une erreur au niveau global si l'ensemble du hub est hors connexion et qu'aucune ampoule ne peut être contrôlée. Si tous les appareils sont hors connexion, il n'y a aucune différence entre les erreurs au niveau global et au niveau de l'appareil.

Lorsqu'un appareil est hors connexion, vous devez signaler {"online": false} à Report State dans les cinq minutes suivant le comportement de l'appareil.

En résumé :

• Erreur au niveau global: tous les appareils de la réponse présentent la même erreur
• Erreur au niveau local: réponse mixte avec des cas d'erreur et de réussite

Erreurs au niveau global

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

Exemple d'erreur deviceOffline au niveau global en raison de l'état hors connexion du hub:

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

Exemple d'erreur inSoftwareUpdate au niveau global en raison de la mise à jour du hub:

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

Erreurs au niveau de l'appareil

Réponse QUERY

L'extrait 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 JSON suivant montre comment signaler des 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 JSON suivant montre comment signaler des 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 génèrent la synthèse vocale associée sur l'appareil.

Exceptions

Vous devez renvoyer une exception lorsqu'un problème ou une alerte est 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 un exceptionCode approprié (pour l'appareil cible).

Par exemple, si le filtre à peluches du sèche-linge est plein, l'utilisateur peut toujours démarrer son sèche-linge, mais vous pouvez l'avertir de cet état. De même, lorsqu'un appareil a une batterie faible mais pas vide, vous pouvez toujours exécuter une commande, mais vous devez l'informer que la batterie de l'appareil est faible.

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 (SUCCÈS) concernant l'appareil cible

Cet exemple concerne le verrouillage de la porte:

La batterie de la serrure de la porte d'entrée est faible. 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 (SUCCÈS) concernant un autre appareil à l'aide de StatusReport

Cet exemple concerne l'activation d'un système de sécurité: OK, j'active le système de sécurité. La fenêtre de devant 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"
        }]
      }
    }]
  }
}

Exception de blocage concernant 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 génèrent la synthèse vocale associée sur l'appareil.