Erreurs et exceptions

Ce document liste les erreurs et exceptions officiellement acceptées pour les appareils connectés. Veuillez utiliser les codes d'erreur et d'exception fournis dans la réponse de l'intent ou dans les notifications si vous les avez implémentées, afin que l'Assistant Google alerte les utilisateurs finaux des problèmes liés à une commande ou à un état de l'appareil donnés. 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é, 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 d'interrogation. Par exemple, si une serrure de porte est bloquée et ne peut pas être verrouillée ou 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 au niveau global. Par exemple, si un utilisateur possède de nombreuses lampes d'un même fournisseur et qu'elles sont contrôlées par un hub, lorsqu'il demande à éteindre toutes ses lampes, le fournisseur peut renvoyer une erreur au niveau de l'appareil si une seule lampe est hors connexion, ou une erreur au niveau global si l'ensemble du hub est hors connexion et qu'aucune lampe ne peut être contrôlée. Si tous les appareils sont hors connexion, il n'y a aucune différence entre l'utilisation d'erreurs au niveau global ou au niveau 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 une réponse QUERY ou EXECUTE.

Exemple d'erreur au niveau global deviceOffline due au fait que le hub est hors connexion :

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

Exemple d'erreur au niveau global inSoftwareUpdate due à 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 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 le TTS associé sur l'appareil.

Rapports sur l'état en ligne et hors connexion

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

Exceptions

Vous devez renvoyer une exception lorsqu'un problème ou une alerte sont associés à une commande. La commande peut réussir ou échouer.

Si la commande a abouti (é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 (SUCCESS) 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 (SUCCESS) concernant un autre appareil utilisant StatusReport

Cet exemple concerne l'activation d'un système de sécurité : OK, j'active le système de sécurité. La vitre avant 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 utilisant 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 le TTS associé sur l'appareil.