Errori ed eccezioni

Questo documento elenca gli errori e le eccezioni supportati ufficialmente per i dispositivi per la smart home. Utilizza gli errori e i codici di eccezione indicati nella risposta all'intent o nelle notifiche, se l'hai implementata, in modo che l'Assistente Google avvisi gli utenti finali di problemi relativi a un determinato comando o stato del dispositivo. Se la risposta contiene una formattazione errata o errorCode, l'Assistente Google mostra agli utenti un messaggio di errore generico, ad esempio "Spiacenti, dispositivo non è al momento disponibile".

Errori

Devi restituire un codice di errore quando un problema causa il mancato completamento di una richiesta di esecuzione o di query. Ad esempio, se una serratura della porta è bloccata e non può essere chiusa o aperta, all'utente dovrebbe essere restituito un errore relativo a questo stato.

I codici di errore possono essere associati a livello di dispositivo o a livello globale. Ad esempio, se un utente ha molte luci di un provider e queste sono controllate da un hub, quando l'utente chiede di spegnere tutte le luci, il provider potrebbe restituire un errore a livello di dispositivo se una singola luce è offline o un errore a livello globale se l'intero hub è offline e non è possibile controllare nessuna luce. Se tutti i dispositivi sono offline, non c'è alcuna differenza tra l'utilizzo di errori a livello globale o a livello di dispositivo. Quando un dispositivo è offline, devi segnalare lo stato {"online": false} in reportState anche se restituisci il codice di errore deviceOffline.

In sintesi:

  • Errore a livello globale: tutti i dispositivi nella risposta hanno lo stesso errore
  • Errore a livello locale: risposta mista con casi di errore e casi di successo

Errori a livello globale

Lo snippet JSON riportato di seguito mostra come restituire errori a livello globale nella risposta QUERY o EXECUTE.

Un esempio di errore a livello globale deviceOffline dovuto all'hub è offline:

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

È in corso l'aggiornamento di un esempio di errore a livello globale inSoftwareUpdate dovuto all'hub:

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

Errori a livello di dispositivo

Risposta QUERY

Lo snippet JSON riportato di seguito mostra come restituire errori a livello di dispositivo nella risposta QUERY.

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

ESEGUI risposta

Lo snippet JSON riportato di seguito mostra come restituire errori a livello di dispositivo nella risposta 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
        }
      }
    ]
  }
}

Notifiche con errori

Notifica proattiva

Lo snippet JSON riportato di seguito mostra come segnalare gli errori a livello di dispositivo in una notifica proattiva.

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

Risposta di follow-up

Lo snippet JSON riportato di seguito mostra come segnalare errori a livello di dispositivo in una risposta di follow-up.

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

Elenco di errori

I seguenti errori produrranno il TTS associato sul dispositivo.

  • abovemaximumLightEffectsDuration : superiore alla durata massima di 1 ora. Riprova.
  • abovemaximumTimerDuration : Posso impostare <device(s)> solo per un massimo di <time period>
  • actionNotAvailable : Mi dispiace, non posso farlo al momento.
  • actionavailableWhenRunning : <device(s)> <is/are> attualmente in esecuzione, quindi non posso apportare alcuna modifica.
  • alreadyArmed : <device(s)> <is/are> già abilitato.
  • alreadyAtMax : <device(s)> <is/are> già impostato sulla temperatura massima.
  • alreadyAtMin : <device(s)> <is/are> già impostato sulla temperatura minima.
  • alreadyClosed : <device(s)> <is/are> already closed.
  • alreadyDisarmed : <device(s)> <is/are> già disabilitato.
  • Già inserito nel dock : <device(s)> <is/are> già inserito nel dock.
  • alreadyInState : <device(s)> <is/are> è già in quello stato.
  • già Bloccato : <dispositivo(i)> <è/sono> già bloccato.
  • alreadyOff : <device(s)> <is/are> already off.
  • alreadyOn : <device(s)> <is/are> already on.
  • alreadyOpen : <device(s)> <is/are> already open.
  • alreadyPausa : <device(s)> <is/are> già in pausa.
  • alreadyStarted : <device(s)> <is/are> already started.
  • alreadySSuggested : <device(s)> <is/are> già arrestati.
  • alreadySbloccati : <device(s)> <is/are> già sbloccati.
  • ambiguousZoneName : Spiacenti, impossibile identificare la zona di <device(s)> in quale zona ti riferisci. Assicurati che le zone abbiano nomi univoci e riprova.
  • quantityAboveLimit : Più di quanto possa essere supportato da <device(s)>.
  • appLaunch locale : Spiacenti, impossibile avviare <nome app> su <dispositivi>.
  • armFailure : Impossibile abilitare <device(s)>.
  • armLevelneeded : Non so con certezza su quale livello impostare <device(s)>. Prova a dire "Imposta <dispositivi> su <sicurezza bassa>" o "Imposta <dispositivi> su <sicurezza alta>"
  • authFailure : Non riesco a raggiungere <device(s)>. Prova a controllare l'app per assicurarti che <device/devices> <is/are> sia completamente configurato.
  • bagFull : <device(s)> <has/have> <a full bag/full bag>. Svuota <it/them> e riprova.
  • belowminimumLightEffectsDuration : meno della durata minima di 5 minuti. Riprova.
  • belowminimumTimerDuration : Non riesco a impostare <device(s)> per un periodo di tempo così breve. Riprova.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • cancelArmingRestricted : Spiacenti, non ho potuto annullare l'abilitazione di <device(s)>.
  • cancelTooLate : Spiacenti, è troppo tardi per annullare. Usa <device(s)> o l'app.
  • channelSwitchImpression : Spiacenti, impossibile passare al canale <nome del canale>. Riprova più tardi.
  • caricabatterieProblema : Spiacenti, sembra che <device(s)> <has/have> <a caricabatterie issue/charger issues>.
  • comandoInsertImpression : Impossibile elaborare comandi per <device(s)>.
  • scaricabatteria : <device(s)> <has/have> <a scarico/batteria scarica>.
  • gradiOutOfRange : I gradi richiesti sono fuori intervallo per <device(s)>.
  • deviceAlertRequireAssistance : <device(s)> <has/have> un avviso attivo e <need(s)> la tua assistenza.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura/temperature estreme>.
  • deviceBusy : Mi spiace, sembra che <device(s)> stia già facendo qualcosa in questo momento.
  • deviceRicarica : Mi spiace, sembra che <device(s)> non possa farlo perché (ha_shared.Its theyre size=$item.devices.total_device_count) è in carica.
  • deviceClogged : Spiacenti, sembra che <device(s)> sia intasato.
  • deviceAttualmenteDispensing : <device(s)> sta già erogando qualcosa in questo momento.
  • deviceDoorOpen : La porta è aperta su <device(s)>. Chiudila e riprova.
  • deviceHandleClosed : La maniglia è chiusa su <device(s)>. Aprila e riprova.
  • deviceJammingDetected : <device(s)> <è/sono> bloccati.
  • deviceLidOpen : Il coperchio è aperto su <device(s)>. Chiudilo e riprova.
  • deviceNeedsRepair : <device(s)> <need(s)> to be riveed. Contatta il tuo rivenditore di assistenza locale.
  • deviceNotDocked : Mi dispiace, sembra che <device(s)> <non sia/non sia> inserito nel dock. Aggancia <it/them> e riprova.
  • deviceNotFound : <device(s)> <is/are>non disponibile. Prova a riconfigurarli.
  • deviceNotMounted : Mi spiace, sembra che <device(s)> non possa farlo perché <it/they> <is/are>non sono montati.
  • deviceNotReady : <device(s)> <is/are>n ready.
  • deviceStuck : <device(s)> <is/are> si è bloccato e ha bisogno del tuo aiuto.
  • deviceTampered : <device(s)> <è/sono> stati manomessi.
  • deviceThermalShutdown : Spiacenti, sembra che <device(s)> si sia spento a causa delle temperature estreme.
  • directResponseSoloUnreachable : <device(s)> <non/non> supporta il controllo remoto.
  • disarmFailure : Impossibile disabilitare <device(s)>.
  • discreteOnlyOpenClose : Spiacenti, è possibile aprire o chiudere completamente i <device(s)>.
  • dispenseAmountAboveLimit : <device(s)> non può erogare una quantità così grande.
  • dispenseAmountBelowLimit : <device(s)> non può erogare una quantità così ridotta.
  • dispenseAmountRemainingExceeded : <device(s)> non dispone di <dispense item> sufficiente per eseguire questa operazione.
  • dispenseFractionalAmountNotSupported : <device(s)> non può erogare frazioni di <dispense item>.
  • dispenseFractionalUnitNotSupported : <device(s)> non supporta frazioni dell'unità per <dispense item>.
  • dispenseUnitNotSupported : <device(s)> non supporta quell'unità per <dispense item>.
  • doorClosedTooLong : È passato un po' di tempo dall'ultima volta che la porta di <device(s)> è stata aperta. Apri la porta, assicurati che ci sia qualcosa all'interno e riprova.
  • emergenzaRiscaldamento : <device(s)> <is/are> in modalità di riscaldamento di emergenza, pertanto <it/they> devono essere regolati manualmente.
  • difettosa batteria : <device(s)> <ha/have> <una batteria difettosa/batterie difettose>.
  • pianoNon raggiungibile : <device(s)> non può raggiungere quella stanza. Sposta <it/them> sul piano giusto e riprova.
  • FunctionsNotSupported : In realtà, <device(s)> <non/non> supporta questa funzionalità.
  • genericheDispenseNotSupported : Devo sapere cosa vuoi erogare. Riprova inserendo il nome dell'articolo.
  • hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il dispositivo per la casa.
  • hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il dispositivo per la casa.
  • inAutoMode : <device(s)> <is/are> attualmente impostato sulla modalità automatica. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • inAwayMode : <device(s)> <is/are> attualmente impostato sulla modalità Fuori. Per controllare il termostato, dovrai passare manualmente alla modalità A casa utilizzando l'app Nest su telefono, tablet o computer.
  • inDryMode : <device(s)> <is/are> attualmente impostato sulla modalità di deumidificazione. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • inEcoMode : <device(s)> <is/are> attualmente impostato sulla modalità eco. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • inFanOnlyMode : <device(s)> <is/are> attualmente è impostato sulla modalità di sola ventola. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • inCaldoOFreddo : <dispositivo(i)> <è/non è in modalità Caldo/Freddo.
  • inHumidifierMode : <device(s)> <is/are> attualmente è impostato sulla modalità umidificatore. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • ModalitàOff : <device(s)> <is/are> attualmente spenti. Per cambiare la temperatura devi passare <it/them > a un'altra modalità.
  • inPurifierMode : <device(s)> <is/are> attualmente impostato sulla modalità di purificazione. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
  • inSleepMode : <device(s)> <is/are> in modalità sonno. Riprova più tardi.
  • inSoftwareUpdate : <device(s)> <is/are> attualmente in fase di aggiornamento software.
  • lockFailure : Impossibile bloccare <device(s)>.
  • lockState : <device(s)> <is/are> attualmente bloccati.
  • lockToRange : La temperatura non rientra nell'intervallo bloccato su <device(s)>.
  • Batteria in esaurimento : <device(s)> <ha/hanno> la batteria in esaurimento.
  • maxSettingReached : <device(s)> <is/are> è già impostato sull'impostazione massima.
  • maxSpeedReached : <device(s)> <is/are> è già impostato sulla velocità massima.
  • minSettingReached : <device(s)> <is/are> è già impostato sull'impostazione più bassa.
  • minSpeedReached : <device(s)> <is/are> è già impostato sulla velocità minima.
  • monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connessione al servizio di monitoraggio.
  • needAllegato : Spiacenti, sembra che <device(s)> <is/are> manchi un allegato obbligatorio. Sostituiscila e riprova.
  • needBin : Spiacenti, sembra che <device(s)> <is/are> manchi un contenitore. Sostituiscila e riprova.
  • needPads : <device(s)> <need(s)> nuovi pad.
  • needSoftwareUpdate : <device(s)> <need(s)> un aggiornamento software.
  • needwater : <device(s)> <need(s)> water.
  • networkProfileNotRecognized : Spiacenti, non riconosco "<profilo di rete>" su <device(s)>.
  • networkSpeedTestInProgress : Sto già testando <network> <speed/speeds>>.
  • noAvailableApp : Spiacenti, sembra che <app name> non sia disponibile.
  • noAvailableChannel : Spiacenti, sembra che il canale <nome canale> non sia disponibile.
  • noChannelSubscription : Spiacenti, al momento non hai effettuato l'iscrizione al canale <channel name>.
  • noTimerExists : Mi spiace, sembra che non ci siano timer impostati su <device(s)>.
  • notSupportato : Spiacenti, questa modalità non è disponibile per <device(s)>.
  • ostruita : <device(s)> ha rilevato un'ostruzione.
  • offline , deviceOffline : Spiacenti, sembra che <device(s)> <is/are>non sia disponibile al momento.
  • onRequiresMode : Specifica la modalità che vuoi attivare.
  • passphrase errata : Mi spiace, sembra che il PIN non sia corretto.
  • percentOutOfRange : Mi dispiace, non posso impostare <device(s)> su <percent>.
  • pinrisposta : (passphrase errata)
  • rilevamento di pioggia : Non ho aperto <device(s)> perché è stata rilevata pioggia.
  • rangeTooClose : Sono troppo vicini per un intervallo Caldo-Freddo per <device(s)>. Scegli temperature più lontane.
  • relinkRequired : Spiacenti, sembra che si sia verificato un problema con il tuo account. Usa l'app Google Home o dell'assistente per ricollegare <dispositivi>.
  • remoteSetDisabled :
    • Parametro facoltativo errorCodeReason
    • currentlyArmed - Spiacenti, la sicurezza è già abilitata, devi usare <device(s)> o l'app per apportare modifiche.
    • remoteUnlockNotAllowed - Mi dispiace, non posso sbloccare <device(s)> da remoto.
    • remoteControlOff - Al momento questa azione è disattivata. Attiva il controllo remoto sui <dispositivi> e riprova.
    • childSafetyModeActive - L'azione è disattivata per <dispositivi> quando è attiva la modalità protezione bambini.
  • roomOnDifferentFloors : <device(s)> non può raggiungere quelle stanze perché si trovano su piani diversi.
  • safetyShutOff : <device(s)> <is/are> in modalità di arresto di sicurezza, pertanto <it/they>> devono essere regolati manualmente.
  • sceneCannotBeApplied : Spiacenti, non è possibile applicare <device(s)>.
  • securityRestriction : <device(s)> <presenta/hanno> una limitazione di sicurezza.
  • softwareUpdateNotAvailable : Spiacenti, non sono disponibili aggiornamenti software su <device(s)>.
  • startRequiresTime : A tale scopo, devi dirmi per quanto tempo vuoi eseguire <device(s)>.
  • stillCoolingDown : <device(s)> <is/are> si sta ancora raffreddando.
  • stillWarmingUp : <device(s)> <is/are> è ancora in fase di preparazione.
  • streamavailable : Spiacenti, sembra che lo stream non sia al momento disponibile su <device(s)>.
  • streamUnplayable : Mi dispiace, non posso riprodurre lo stream da <device(s)> al momento.
  • containerVuoto : <device(s)> <has/have> <an empty tank/emptys>. Riempi <it/them> e riprova.
  • targetAlreadyReached : Mi dispiace, sembra che questa sia già la temperatura attuale.
  • timerValueOutOfRange : Impossibile impostare <device(s)> per questo periodo di tempo.
  • to manyfailtents : Spiacenti, sono presenti troppi tentativi non riusciti. Vai all'app del dispositivo per completare l'azione.
  • transientError : Spiacenti, si è verificato un problema durante il controllo di <device(s)>. Riprova.
  • off , deviceTurnedOff : <device(s)> <is/are> off now.
  • allowToLocateDevice : Non ho potuto trovare <device(s)>.
  • unknownFoodPreset : <device(s)> non supporta quel programma predefinito per alimenti.
  • UnlockFailure : Impossibile sbloccare <device(s)>.
  • unpausableState : al momento non è possibile mettere in pausa <device(s)>.
  • userAnnullata : ok
  • valueOutOfRange : Impossibile impostare <device(s)> su questa temperatura.

Eccezioni

Devi restituire un'eccezione quando si verifica un problema o un avviso associato a un comando. Il comando potrebbe avere esito positivo o negativo.

Se il comando ha avuto esito positivo (status = "SUCCESS"), segnala le eccezioni utilizzando il trait StatusReport (per i dispositivi diversi dal target) o restituendo un exceptionCode appropriato (per il dispositivo di destinazione).

Ad esempio, se la schermata di pelucchi dell'asciugatrice è piena, l'utente può comunque avviare l'asciugatrice, ma potresti volerlo avvisare di questo stato. Allo stesso modo, quando la batteria di un dispositivo è in esaurimento, puoi comunque eseguire un comando, ma comunicandogli che la batteria del dispositivo è in esaurimento.

Se il comando non riesce a causa di eccezioni, lo stato dovrebbe essere "EXCEPTIONS" e le eccezioni devono essere segnalate utilizzando il trait StatusReport.

Eccezione che non blocca (SUCCESS) sul dispositivo di destinazione

Ecco un esempio per chiudere la serratura della porta:

Batteria della serratura della porta principale in esaurimento. Chiudo la porta d'ingresso.

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

Eccezione che non blocca (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport

Questo esempio riguarda l'abilitazione di un sistema di sicurezza: Ok, sto abilitando il sistema di sicurezza. Il finestrino anteriore è aperto.

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

Blocco dell'eccezione relativa a un altro dispositivo tramite 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"
          }
        ]
      }
    }
  }
}

Elenco delle eccezioni

Le seguenti eccezioni generano il TTS associato sul dispositivo.

  • bagFull : <device(s)> <has/have> <a full bag/full bag>. Svuota <it/them> e riprova.
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carbonMonoxide Detected : È stato rilevato monossido di carbonio in <nome della casa>.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura/temperature estreme>.
  • deviceJammingDetected : <device(s)> <è/sono> bloccati.
  • deviceMoved : <device(s)> <è stato/sono stati spostati.
  • deviceOpen : <device(s)> <is/are> open.
  • deviceTampered : <device(s)> <è/sono> stati manomessi.
  • deviceUnplugged : <device(s)> <is/are> scollegato.
  • pianoNon raggiungibile : <device(s)> non può raggiungere quella stanza. Sposta <it/them> sul piano giusto e riprova.
  • hardwareFailure : <device(s)> <ha/ha> un problema hardware.
  • inSoftwareUpdate : <device(s)> <is/are> attualmente in fase di aggiornamento software.
  • Bypassato : <device(s)> <is/are> attualmente ignorato.
  • Batteria in esaurimento : <device(s)> <ha/hanno> la batteria in esaurimento.
  • motionDetected : <device(s)> <detect(s)> motion.
  • needPads : <device(s)> <need(s)> nuovi pad.
  • needSoftwareUpdate : <device(s)> <need(s)> un aggiornamento software.
  • needwater : <device(s)> <need(s)> water.
  • networkJammingDetected : la connessione della rete di casa a <device(s)> non funziona correttamente.
  • noIssuesReported : <device(s)> non ha segnalato problemi.
  • roomOnDifferentFloors : <device(s)> non può raggiungere quelle stanze perché si trovano su piani diversi.
  • runCycleFinished : Esecuzione di<device(s)> <has/have> terminata.
  • securityRestriction : <device(s)> <presenta/hanno> una limitazione di sicurezza.
  • Rilevato fumo : È stato rilevato fumo in <nome casa>.
  • containerVuoto : <device(s)> <has/have> <an empty tank/emptys>. Riempi <it/them> e riprova.
  • utilizzando CellularBackup : <device(s)> <is/are> usando il backup da rete mobile.
  • waterLeakDetected : <device(s)> <detect(s)> una perdita d'acqua.