Errori ed eccezioni

Questo documento elenca gli errori e le eccezioni ufficiali supportati per i dispositivi per la smart home. Utilizza questi codici di errore ed eccezioni nella risposta dell'intent o nelle notifiche se l'hai implementato, in modo che gli avvisi dell'Assistente Google vengano segnalati agli utenti in caso di problemi relativi a un determinato comando o stato del dispositivo. Se la risposta contiene una formattazione errata o errorCode, l'Assistente Google visualizza un messaggio di errore generico per gli utenti, ad esempio"dispositivo non è al momento disponibile.

Errori

Dovresti restituire un codice di errore quando un problema causa l'esito negativo di una richiesta di esecuzione o query. Ad esempio, se una serratura è bloccata e non può essere bloccata o aperta, deve essere restituito all'utente un errore in questo stato.

I codici di errore possono essere allegati a livello di dispositivo o a livello globale. Ad esempio, se un utente ha molte luci di un fornitore e sono controllate da un hub, quando chiede di spegnere tutte le luci, il fornitore 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 errori e casi di successo

Errori a livello globale

Il seguente snippet JSON mostra come si restituiscono gli 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"
  }
}

Esempio di errore a livello globale inSoftwareUpdate dovuto all'aggiornamento dell'hub:

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

Errori a livello di dispositivo

Risposta QUERY

Il seguente snippet JSON 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

Il seguente snippet JSON mostra come restituire errori a livello di dispositivo nella risposta ESECUZIONE.

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

Il seguente snippet JSON mostra come segnalare 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

Il seguente snippet JSON 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 generano la sintesi vocale associata sul dispositivo.

  • above MaximumLightEffettosDuration : superiore alla durata massima di 1 ora. Riprova.
  • above MaximumDurationDuration : Posso impostare solo <device(s)> per un massimo di <periodo di tempo>
  • actionNotAvailable : Mi dispiace, non posso farlo adesso.
  • actionAvailableDuringRunning : <device(s)> <is/are> attualmente in esecuzione, quindi non posso apportare alcuna modifica.
  • Integrato : <device(s)> <is/are> già abilitato.
  • firstAtMax : <dispositivo/i> <è/sono> già impostato sulla temperatura massima.
  • alreadyAtMin : <device(s)> <is/are> è già impostato sulla temperatura minima.
  • giàChiuso : <dispositivo/i> <è/sono> già chiuso.
  • alreadyDisarmed : <device(s)> <is/are> è già disabilitato.
  • alreadyDocked : <device(s)> <è/sono> 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> già off.
  • onOn : <i dispositivi> <è/sono> già attivo.
  • GiàAperto : <dispositivo/i> <è/sono> già aperto.
  • tecnologia già in pausa : <dispositivo/i> <è/sono> già in pausa.
  • Già avviato : <dispositivo/i> <è/sono> già avviato.
  • alreadySstop : <device(s)> <is/are> è già stato interrotto.
  • Già sbloccato : <dispositivo/i> <è/sono> già sbloccato.
  • ambiguousZoneName : Spiacenti, <device(s)> non è in grado di identificare la zona che intendi. Assicurati che le zone abbiano nomi univoci e riprova.
  • amountAboveLimit : È una quantità superiore a quella supportata dai dispositivi <device(s)>.
  • appLaunchFailed : Spiacenti, impossibile avviare <app name> su <device(s)>.
  • armFailure : Non è stato possibile abilitare <device(s)>.
  • armLevelRequireded : Non so con quale livello impostare <device(s)>. Prova a dire "Imposta <dispositivo/i>> su <bassa sicurezza>" o "Imposta <dispositivo/i>> su <alta sicurezza>"
  • authFailure : Non riesco a raggiungere <device(s)>. Prova a controllare l'app per assicurarti che il dispositivo <device/devices> <is/are> sia completamente configurato.
  • bagFull : <device(s)> <has/have> <a full bag/full bag>. Svuota <it/them> e riprova.
  • belowMinimumLightEffettosDuration : Si tratta di una durata inferiore a 5 minuti. Riprova.
  • belowMinimumTimerDuration : Non posso impostare <device(s)> per un tempo così breve. Riprova.
  • binFull : <device(s)> <has/have> <a full bin/full bins>
  • cancelArmingRestricted : Mi dispiace, non ho potuto annullare l'abilitazione dell'inserimento di <device(s)>.
  • cancelTooLate : Spiacenti, è troppo tardi per annullare. Usa <device(s)> o l'app.
  • channelSwitchFailed : Spiacenti, impossibile passare al canale <channel name>. Riprova più tardi.
  • caricabatterieIssue : Sembra che <device(s)> <has/have> <a caricabatterie issue/charger issues>.
  • CommandInsertFailed : Impossibile elaborare i comandi per <device(s)>.
  • deadBatteria : <dispositivo/i> <ha/ha> <una batteria scarica/batteria esaurita>.
  • gradiOutOfRange : I gradi richiesti sono fuori intervallo per <device(s)>.
  • deviceAlertNeedsAssistance : <device(s)> <has/have> un avviso attivo e <need(s)> la tua assistenza.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura estrema/temperature estreme>.
  • deviceBusy : Spiacenti, sembra che <device(s)> stia già facendo qualcosa in questo momento.
  • deviceCharge : Mi dispiace, non è possibile farlo con <device(s>) perché (ha_shared.ItsArere size=$item.devices.total_device_count) in carica.
  • deviceClogged : Mi dispiace, <device(s)> è intasato.
  • deviceAl momento di erogazione : dispositivo/i> sta già erogando qualcosa.
  • deviceDoorOpen : La porta è aperta su <device(s)>. Chiudila e riprova.
  • deviceHandleClosed : L'handle è chiuso su <device(s)>. Aprila e riprova.
  • deviceJammingDetected : <device(s)> <is/are> è bloccato.
  • deviceLidOpen : Il coperchio è aperto su <device(s)>. Chiudilo e riprova.
  • deviceneedsRepair : <device(s)> <need(s)> da riparare. Contatta il rivenditore locale.
  • deviceNotDocked : Sembra che <device(s)> <non sia/non sia> inserito nel dock. Inserisci <it/them> e riprova.
  • deviceNotFound : i dispositivi> <is/are>non sono disponibili. Prova a riconfigurarli.
  • deviceNotMounted : Mi dispiace, non è possibile farlo con <device(s>) perché <it/there> <is/are>non sono montati.
  • deviceNotReady : <device(s)> <è/sono>non pronto.
  • deviceStuck : <device(s)> <is/are> è bloccato e ha bisogno del tuo aiuto.
  • deviceTampered : <device(s)> <sono stati manomessi>.
  • deviceThermalShutdown : Sembra che <device(s)> si sia spento a causa delle temperature estreme.
  • directResponseOnlyUnreachable : <device(s)> <non/non> supporta il controllo remoto.
  • disarmFailure : Non è stato possibile disabilitare <device(s)>>.
  • discreteOnlyOpenClose : Spiacenti, i dispositivi <device(s)> possono essere solo aperti o chiusi solo per intero.
  • dispenseAmountAboveLimit : <device(s>>) non può erogare una quantità così grande.
  • dispenseAmountUnderLimit : <device(s)> non può erogare una quantità così bassa.
  • dispenseAmountRemainingExceeded : <device(s)> non ha abbastanza <dispense item> per farlo.
  • dispenseFractionalAmountNotsupported : <device(s)> non può erogare frazioni di <dispense item>.
  • dispenseFractionalUnitNotsupported : <dispositivo/i> non supporta le frazioni di questa unità per <elemento di erogazione>.
  • dispenseUnitNotsupported : <dispositivo/i> non supporta quell'unità per <elemento di erogazione>.
  • doorClosedToolong : È passato un po' di tempo dall'apertura della porta su <device(s)>. Apri la porta, assicurati che ci sia qualcosa all'interno e riprova.
  • emergenzeHeatOn : <dispositivo/i> <è/sono> in modalità Caldo di emergenza, quindi <it/tai> dovranno essere regolati manualmente.
  • difettosaBatteria : <dispositivo/i> <ha/ha> <una batteria difettosa/batterie difettose>.
  • Floor Unreachable : <device(s)> non può raggiungere la stanza. Spostalo <it/them> al piano giusto e riprova.
  • functionNotSupportato : In realtà, <device(s)> <non supporta/non> supporta questa funzionalità.
  • genericDispenseNotsupported : Ho bisogno di sapere cosa vorresti erogare. Riprova con 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/them> a una modalità diversa.
  • inAwayMode : <device(s)> <is/are> attualmente impostato sulla modalità Fuori. Per controllare il termostato, devi attivare manualmente la modalità A casa utilizzando l'app Nest su telefono, tablet o computer.
  • inDryMode : <device(s)> <is/are> attualmente impostato sulla modalità Deumidifica. Per cambiare la temperatura devi passare <it/them> a una modalità diversa.
  • inEcoMode : <device(s)> <is/are> attualmente impostato sulla modalità eco. Per cambiare la temperatura devi passare <it/them> a una modalità diversa.
  • inFanOnlyMode : <device(s)> <is/are> attualmente impostato sulla modalità solo ventola. Per cambiare la temperatura devi passare <it/them> a una modalità diversa.
  • inHeatOrCool : <dispositivo/i> <non è/non è in modalità Caldo/Freddo.
  • inHumidifierMode : <device(s)> <is/are> attualmente impostato sulla modalità umidificatore. Per cambiare la temperatura devi passare <it/them> a una modalità diversa.
  • inOffMode : <device(s)> <is/are> attualmente spento. Per cambiare la temperatura devi passare <it/them > a un'altra modalità.
  • inPurifierMode : <device(s)> <is/are> attualmente impostato sulla modalità purificatore. Per cambiare la temperatura devi passare <it/them> a una modalità diversa.
  • inSleepMode : <device(s)> <is/are> in modalità di sospensione. Riprova più tardi.
  • in SoftwareUpdate : <device(s)> <is/are> attualmente in un aggiornamento software.
  • lockFailure : Non è stato possibile bloccare <device(s)>>.
  • lockState : <device(s)> <is/are> attualmente bloccato.
  • lockToRange : La temperatura non rientra nell'intervallo bloccato dei dispositivi <device(s)>.
  • batteria bassa : <dispositivo/i> <ha/ha>la batteria in esaurimento.
  • maxSettingReached : <device(s)> <is/are> è già impostata sul valore più alto.
  • maxSpeedReached : <device(s)> <è/sono> già impostato sulla velocità massima.
  • minSettingReached : <device(s)> <is/are> è già impostata sul valore più basso.
  • minSpeedReached : <dispositivo/i> <è/sono> già impostato sulla velocità minima.
  • monitoringServiceConnectionLost : <device(s)> <has/have> perso <its/their> connessione al servizio di monitoraggio.
  • needAttachment : Spiacenti, in <device(s)> <is/are> manca un allegato obbligatorio. Sostituiscila e riprova.
  • needBin : Spiacenti, a <device(s)> <is/are> manca 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)> acqua.
  • networkProfileNotRecognized : Mi dispiace, non riconosco "<network network>" su <device(s)>.
  • networkSpeedTestInProgress : Sto già testando <network> <speed/speeds>>.
  • noAvailableApp : Mi dispiace, non sembra che <app name> sia disponibile.
  • noAvailableChannel : Sembra che il canale <channel name> non sia disponibile.
  • noChannelIscrizione : Al momento non hai effettuato l'iscrizione al canale <nome canale>.
  • noTimerExists : Mi dispiace, non ci sono timer impostati su <device(s)>.
  • notsupported : Mi dispiace, questa modalità non è disponibile per <device(s)>.
  • ostruzioni rilevate : <dispositivi> hanno rilevato un'ostruzione.
  • offline , deviceOffline : Spiacenti, sembra che <device(s)> <is/are>non sia disponibile al momento.
  • onRequestsMode : Specifica quale modalità vuoi attivare.
  • passphraseOK : Sembra che il PIN non sia corretto.
  • percentOutOfRange : Mi dispiace, non posso impostare <device(s)> su <percent>.
  • pinEsatto : (passphraseIncorrect)
  • RainDetected : Non ho aperto <device(s)> perché è stata rilevata pioggia.
  • rangeTooClose : Questi intervalli sono troppo vicini per un intervallo Heat-Cool per <device(s)>. Scegli temperature più distanziate.
  • relinkRequired : Sembra che si sia verificato un problema con il tuo account. Usa l'app Google Home o dell'assistente per ricollegare <dispositivi(i)>.
  • remoteSetDisabled :
    • Parametro facoltativo errorCodeReason
    • currentlyArmed - Mi dispiace, il sistema di sicurezza è già abilitato, quindi per apportare eventuali modifiche devi utilizzare <device(s)> o l'app.
    • remoteUnlockNotAllowed - Mi dispiace, non posso sbloccare <device(s)> da remoto.
    • remoteControlOff - Al momento questa azione è disattivata. Attiva il controllo remoto su <device(s)> e riprova.
    • childSafetyModeActive - Questa azione è disattivata per <device(s)> mentre è attiva la modalità sicurezza dei bambini.
  • roomOnDifferentFloors : <device(s)> non può raggiungere quelle stanze perché sono su piani diversi.
  • safetyShutOff : <dispositivo/i> <è/sono> in modalità di arresto di sicurezza, quindi <it/loro> dovranno essere regolati manualmente.
  • sceneCanBeApplied : Impossibile applicare <device(s)>.
  • securityRestriction : <device(s)> <has/have> a limitazioni di sicurezza.
  • softwareUpdateNotAvailable : Spiacenti, non ci sono aggiornamenti software disponibili su <device(s)>.
  • startRequestsTime : Per farlo, devi dirmi per quanto tempo vuoi eseguire <device(s)>.
  • stillCoolingDown : <device(s)> <is/are> ancora in raffreddamento.
  • stillWarmingUp : Il dispositivo/i dispositivi <is/are> è ancora in fase di riscaldamento.
  • stream non disponibile : Sembra che attualmente lo stream non sia disponibile da <device(s)>.
  • streamUnplayable : Mi dispiace, al momento non posso riprodurre lo stream da <device(s)>.
  • tankempty : <device(s)> <has/have> <un vuoto/serbatoi vuoti>. Compila <it/them> e riprova.
  • targetAlreadyReached : Mi dispiace, è già la temperatura attuale.
  • timerValueOutOfRange : Non è possibile impostare <device(s)> per questo periodo di tempo.
  • TooManyRetryRetrys : Spiacenti, troppi tentativi non riusciti. Vai sull'app del tuo dispositivo per completare questa azione.
  • transientError : Spiacenti, si è verificato un problema durante il controllo di <device(s)>. Riprova.
  • off , deviceTurnedOff : <device(s)> <is/are> è disattivato in questo momento.
  • imlocalToIdentifiDevice : 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)>.
  • userCANCEL : ok
  • valueOutOfRange : non è possibile impostare <device(s)> a questa temperatura.

Eccezioni

Dovresti 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 (stato = "SUCCESS"), segnala le eccezioni utilizzando il tratto StatusReport (per i dispositivi diversi dal target) o restituendo un exceptionCode appropriato (per il dispositivo di destinazione).

Ad esempio, se il filtro lanugine per asciugatrice è pieno, l'utente può comunque avviare l'asciugatrice, ma si consiglia di avvisarlo in merito a questo stato. Analogamente, quando una batteria del dispositivo non è scarica, puoi comunque eseguire un comando, ma devi informarlo che la batteria del dispositivo è in esaurimento.

Se il comando ha esito negativo a causa di eccezioni, lo stato dovrebbe essere "ECCEZIONI" e le eccezioni dovranno essere segnalate utilizzando il tratto StatusReport.

Eccezione non bloccante (SUCCESS) sul dispositivo di destinazione

Ecco un esempio per la serratura della porta:

La batteria della serratura della porta principale è in esaurimento. Chiudo la porta principale.

{
  "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 non bloccante (SUCCESS) su un altro dispositivo che utilizza StatusReport

Questo esempio riguarda l'abilitazione di un sistema di sicurezza: OK, l'abilitazione del 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 su un altro dispositivo usando 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 eccezioni

Le seguenti eccezioni produrranno la sintesi vocale associata 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>
  • carbonMonoxideDetected : È stato rilevato monossido di carbonio in <nome della casa>.
  • deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura estrema/temperature estreme>.
  • deviceJammingDetected : <device(s)> <is/are> è bloccato.
  • deviceSpostato : <device(s)> <was/were> spostato.
  • deviceOpen : <device(s)> <is/are> è aperto.
  • deviceTampered : <device(s)> <sono stati manomessi>.
  • deviceScollegato : <device(s)> <è/sono> scollegato.
  • Floor Unreachable : <device(s)> non può raggiungere la stanza. Spostalo <it/them> al piano giusto e riprova.
  • hardwareFailure : <device(s)> <ha/hanno> un problema hardware.
  • in SoftwareUpdate : <device(s)> <is/are> attualmente in un aggiornamento software.
  • è bypassato : <dispositivo/i> <è/sono> attualmente ignorato.
  • batteria bassa : <dispositivo/i> <ha/ha>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)> acqua.
  • 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é sono su piani diversi.
  • runCycleFinished : <device(s)> <has/have>Finish running.
  • securityRestriction : <device(s)> <has/have> a limitazioni di sicurezza.
  • smokeDetected : È stato rilevato fumo in <nome della casa>.
  • tankempty : <device(s)> <has/have> <un vuoto/serbatoi vuoti>. Compila <it/them> e riprova.
  • utilizzando CellularBackup : <device(s)> <is/are> utilizzando il backup da rete mobile.
  • waterLeakDetected : <device(s)> <detect(s)> una perdita d'acqua.