Erreurs et exceptions

Ce document répertorie les erreurs et les exceptions officiellement compatibles avec 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 l'avez implémenté, afin que l'Assistant Google alerte les utilisateurs finaux en cas de problème lié à une commande ou à l'état d'un appareil donné. Si la réponse contient une mise en forme incorrecte ou errorCode, l'Assistant Google renvoie aux utilisateurs un message d'erreur générique, par exemple "Désolé, l'appareil device 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 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 ajoutés au niveau de l'appareil ou au niveau global. Par exemple, si un utilisateur dispose de plusieurs ampoules d'un même fournisseur et qu'elles sont contrôlées par un hub, lorsqu'il demande à éteindre toutes les lumières, le fournisseur peut renvoyer une erreur au niveau de l'appareil si une seule lumière est hors connexion, ou une erreur globale si l'ensemble du hub est hors connexion et qu'aucune lumière ne peut être contrôlée. Si tous les appareils sont hors connexion, il n'existe aucune différence entre l'utilisation d'erreurs globales 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 figurant dans la réponse présentent la même erreur.
• Erreur locale: réponse mixte avec des cas d'erreur et de réussite

Erreurs au niveau global

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

Exemple d'erreur de niveau global deviceOffline due à l'état hors connexion du hub:

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

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

{
  "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 génèrent 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 un exceptionCode approprié (pour l'appareil cible).

Par exemple, si l'écran du sèche-linge est plein, l'utilisateur peut quand même démarrer son sèche-linge, mais vous pouvez l'avertir de cet état. De même, lorsqu'un appareil a une batterie faible qui n'est 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 sert à verrouiller la porte:

Les piles de la serrure 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 (SUCCÈS) concernant un autre appareil utilisant StatusReport

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

Blocage de l'exception concernant un autre appareil à l'aide du rapport d'état

{
  "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éreront la synthèse vocale associée sur l'appareil.