Erreurs et exceptions

Ce document liste les erreurs et exceptions officiellement prises en charge pour les appareils connectés. Veuillez utiliser ces codes d'erreur et d'exception 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 sur les problèmes liés à une commande ou à un état d'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 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 au niveau global. Par exemple, si un utilisateur possède de nombreuses lumières d'un même fournisseur et qu'elles sont contrôlées par un hub, lorsque l'utilisateur demande d'éteindre toutes ses lumières, le fournisseur peut renvoyer une erreur au niveau de l'appareil si une seule lumière est hors connexion, ou une erreur au niveau global si l'ensemble de son hub est hors connexion et qu'aucune lumière 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 mondial

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

Voici un exemple d'erreur deviceOffline au niveau mondial due au fait que le hub est hors connexion :

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

Voici un exemple d'erreur au niveau mondial 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 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 complémentaire

L'extrait JSON suivant montre comment signaler des erreurs au niveau de l'appareil dans une réponse complémentaire.

{
  "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 message 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 en cas de problème ou d'alerte associés à une commande. La commande peut réussir ou échouer.

Si la commande a réussi (état = "SUCCESS"), signalez les exceptions à l'aide du trait StatusReport (pour les appareils autres que l'appareil 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 l'appareil, 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 informer l'utilisateur 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 du trait StatusReport.

Exception non bloquante (SUCCESS) concernant l'appareil cible

Voici un exemple pour verrouiller 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

Voici un exemple d'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 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.