Erros e exceções

Este documento lista os erros e as exceções oficialmente compatíveis com dispositivos de casa inteligente. Use esses códigos de exceção e erros fornecidos na resposta da intent ou nas notificações se você tiver implementado esses códigos. Assim, o Google Assistente alerta os usuários finais sobre problemas relacionados a um determinado comando ou estado do dispositivo. Se a resposta tiver formatação incorreta ou errorCode, o Google Assistente vai mostrar aos usuários uma mensagem de erro genérica, por exemplo, "device is not available now".

Erros

Retorne um código de erro quando um problema fizer com que uma solicitação de execução ou consulta falhe. Por exemplo, se uma fechadura estiver emperrada e não puder ser trancada ou destrancada, um erro sobre esse estado será retornado ao usuário.

Os códigos de erro podem ser anexados no nível do dispositivo ou no nível global. Por exemplo, se um usuário tiver muitas luzes de um provedor e elas forem controladas por um hub, quando o usuário pedir para apagar todas as luzes, o provedor poderá retornar um erro no nível do dispositivo se uma única luz estiver off-line ou um erro global se todo o hub estiver off-line e nenhuma luz puder ser controlada. Se todos os dispositivos estiverem off-line, não vai haver diferença entre usar erros em nível global ou de dispositivo. Quando um dispositivo está off-line, é necessário informar o estado {"online": false} em reportState, mesmo que você retorne o código de erro deviceOffline.

Resumindo:

  • Erro de nível global: todos os dispositivos na resposta têm o mesmo erro
  • Erro no nível local: resposta mista com erros e casos de sucesso

Erros em nível global

O snippet JSON a seguir mostra como retornar erros de nível global na resposta QUERY ou EXECUTE.

Um exemplo de erro em nível global deviceOffline porque o hub está off-line:

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

Um exemplo de erro em nível global inSoftwareUpdate devido ao hub em atualização:

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

Erros no nível do dispositivo

Resposta de QUERY

O snippet em JSON a seguir mostra como retornar erros no nível do dispositivo na resposta da QUERY.

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

EXECUTAR resposta

O snippet JSON a seguir mostra como retornar erros no nível do dispositivo na resposta de EXECUTAR.

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

Notificações com erros

Notificação proativa

O snippet em JSON a seguir mostra como informar erros no nível do dispositivo em uma notificação proativa.

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

Resposta de acompanhamento

O snippet em JSON a seguir mostra como informar erros no nível do dispositivo em uma resposta de acompanhamento.

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

Lista de erros

Os erros a seguir vão produzir a TTS associada no dispositivo.

  • abovemaximumLightEffectsDuration : é mais do que a duração máxima de 1 hora. Tente de novo.
  • aboveMaximizeTimerDuration : Só posso definir <device(s)> para até <período>
  • actionNotAvailable : Não consigo fazer isso no momento.
  • actionUnusedwhileRunning : <device(s)> <is/are> está em execução no momento, por isso não posso fazer nenhuma alteração.
  • alreadyArmed : <device(s)> <is/are> já estão ligados.
  • alreadyAtMax : <device(s)> <is/are> já está definido para a temperatura máxima.
  • alreadyAtMin : <device(s)> <is/are> já está definido para a temperatura mínima.
  • alreadyClosed : <device(s)> <is/are> já estão fechados.
  • jáDesarmed : <dispositivo(s)> <is/are> já está desligado.
  • alreadyDocked : <device(s)> <is/are> já está na base.
  • alreadyInState : <device(s)> <is/are> já estão nesse estado.
  • jáBloqueado : <dispositivo(s)> <está/são> já bloqueado.
  • alreadyOff : <device(s)> <is/are> já estão desligados.
  • alreadyOn : <device(s)> <is/are> já estão ligados.
  • alreadyOpen : <device(s)> <is/are> já estão abertos.
  • already paused : <device(s)> <is/are> já estão pausados.
  • alreadyStarted : <device(s)> <is/are> já foram iniciados.
  • alreadyStopped : <device(s)> <is/are> já parou.
  • alreadyUnlocked : <dispositivo(s)> <is/are> já está desbloqueado.
  • ambiguidadeName : Não foi possível identificar a zona que você quis dizer. Confira se elas têm nomes exclusivos e tente de novo.
  • amountAboveLimit : É mais do que <device(s)> pode oferecer suporte.
  • appLaunchFailed : Falha ao iniciar o <app name> nos <device(s)>.
  • armFailure : Não foi possível ligar <device(s)>.
  • armLevelNeeded : não sei em que nível definir <device(s)>. Tente dizer "Definir <dispositivo(s)> como <baixa segurança>" ou "Definir <dispositivo(s)> como <alta segurança>"
  • authFailure : Não consigo acessar <device(s)>. Tente verificar o app para garantir que <device/devices> <está/estão> totalmente configurado.
  • bagFull : <dispositivo(s)> <tem/tem> <saco cheio/malas cheias>. Esvazie <it/them> e tente novamente.
  • belowMinimumLightEffectsDuration : é menor que a duração mínima de cinco minutos. Tente de novo.
  • belowMinimumTimerDuration : Não consigo definir <device(s)> para um período tão curto. Tente de novo.
  • binFull : <dispositivo(s)> <tem/tem> <uma lixeira/compartimento cheio(s)>.
  • cancelArmingRestricted : Não foi possível cancelar a ativação de <device(s)>.
  • cancelTooLate : É tarde demais para cancelar. Use <device(s)> ou o app.
  • channelSwitchFailed : Ocorreu uma falha ao alternar para o canal <nome do canal>. Tente novamente mais tarde.
  • Problema do carregador : Parece que <dispositivo(s)> <tem/tem> <problema no carregador>.
  • CommandInsertFailed : Não foi possível processar os comandos para <device(s)>.
  • deadBattery : <dispositivos> <tem/têm> <bateria descarregada/baterias descarregadas>.
  • degreesOutOfRange : os graus solicitados estão fora do intervalo para <device(s)>.
  • deviceAlertNeedsAssistance : <device(s)> <tem/tem> um alerta ativo e <necessita(s)> de assistência.
  • deviceAtExtremeTemperatura : <device(s)> <is/are> a <uma temperatura extrema/temperaturas extremas>.
  • deviceBusy : Parece que <device(s)> já está fazendo algo no momento.
  • deviceLoading : Parece que <device(s)> não consegue fazer isso porque (ha_shared.Its theyre size=$item.devices.total_device_count) carregando.
  • deviceClogged : Parece que <device(s)> está entupido.
  • deviceCurrentDispensing : <device(s)> já está liberando algo no momento.
  • deviceDoorOpen : A porta está aberta no <device(s)>. Feche e tente novamente.
  • deviceHandleClosed : o identificador está fechado no <device(s)>. Abra-o e tente novamente.
  • deviceJammingDetected : <dispositivo(s)> <está/estão> emperrado.
  • deviceLidOpen : A tampa do <device(s)> está aberta. Feche e tente novamente.
  • deviceNeedsRepair : <device(s)> <need(s)> para ser consertado. Entre em contato com o provedor de serviços local.
  • deviceNotDocked : Parece que <device(s)> <não está/não está> na base. Encaixe <it/eles> na base e tente novamente.
  • deviceNotFound : <device(s)> <is/are>não está disponível. Tente configurar essa opção novamente.
  • deviceNotMounted : Parece que <device(s)> não pode fazer isso porque <it/eles> <está/não estão> montados.
  • deviceNotReady : <device(s)> <is/are>não está pronto.
  • deviceStuck : <device(s)> <está/estão> travado e precisa de ajuda.
  • deviceTampered : <dispositivos> <foram> adulterados.
  • deviceThermalShutdown : Parece que <device(s)> foi desligado devido a temperaturas extremas.
  • directResponseOnlyUnreachable : <device(s)> <não é/não> aceita controle remoto.
  • disarmFailure : não foi possível desligar <device(s)>.
  • discreteOnlyOpenClose : O <device(s)> só pode ser aberto ou fechado completamente.
  • dispenseAmountAboveLimit : <device(s)> não pode liberar uma quantidade tão grande.
  • dispenseAmountUnderLimit : <device(s)> não pode liberar uma quantidade tão pequena.
  • dispenseAmountinoAmounted : <device(s)> não tem <dispense item> suficiente para fazer isso.
  • dispenseFractionalAmountNotSupported : <device(s)> não pode liberar frações de <dispense item>.
  • dispenseFractionalUnitNotSupported : <device(s)> não é compatível com frações dessa unidade para <dispense item>.
  • dispenseUnitNotSupported : <device(s)> não é compatível com essa unidade para <dispense item>.
  • doorClosedTooLong : Já faz um tempo desde que a porta do <device(s)> está aberta. Abra a porta, confira se há algo dentro dela e tente novamente.
  • emergênciaHeatOn : <dispositivos> <estão/estão> no modo de aquecimento de emergência, portanto, <it/eles> precisam ser ajustados manualmente.
  • faultyBattery : <dispositivo(s)> <tem/tem> <bateria com defeito/baterias com defeito>.
  • floorUnreachable : <device(s)> não consegue chegar a esse ambiente. Coloque <ele/deles> no andar certo e tente de novo.
  • functionNotSupported : Na verdade, <device(s)> <não tem/não> é compatível com essa funcionalidade.
  • generalDispenseNotSupported : Preciso saber o que você quer disponibilizar. Tente novamente usando o nome do item.
  • hardError : Algo deu errado e não consigo controlar seu dispositivo doméstico.
  • hardError : Algo deu errado e não consigo controlar seu dispositivo doméstico.
  • inAutoMode : <dispositivo(s)> <está/são> definido no modo automático. Para mudar a temperatura, escolha outro modo.
  • inAwayMode : <device(s)> <is/are> está definido no modo ausente. Para controlar o termostato, você precisa ativar o modo "Em casa" manualmente usando o app Nest em um smartphone, tablet ou computador.
  • inDryMode : <dispositivos> <está/são> definidos no modo de secagem. Para mudar a temperatura, escolha outro modo.
  • inEcoMode : <dispositivo(s)> <is/are> definido para o modo econômico. Para mudar a temperatura, escolha outro modo.
  • inFanOnlyMode : <device(s)> <is/are> está configurado no modo somente ventilador. Para mudar a temperatura, escolha outro modo.
  • inHeatOrCool : <dispositivos> <não estão no modo de aquecimento/refrigeração.
  • inHumidifierMode : <device(s)> <está/are> definido no modo umidificador. Para mudar a temperatura, escolha outro modo.
  • inOffMode : <device(s)> <is/are> estão desligados. Para mudar a temperatura, troque <it/them> para outro modo.
  • inPurifierMode : <device(s)> <is/are> (dispositivo(s)> <is/are> definido(s) no momento está definido para o modo purificador. Para mudar a temperatura, escolha outro modo.
  • inSleepMode : <device(s)> <está/are> no modo de espera. Tente de novo mais tarde.
  • inSoftwareUpdate : <dispositivo(s)> <está/estão> em uma atualização de software.
  • lockFailure : Não foi possível bloquear <device(s)>.
  • BlockState : <dispositivos> <is/are> bloqueados no momento.
  • BlockToRange : essa temperatura está fora do intervalo bloqueado em <device(s)>.
  • Bateria fraca : <dispositivos> <tem/têm> bateria fraca.
  • maxSettingReached : <device(s)> <is/are> já está definido para a configuração mais alta.
  • maxSpeedReached : <device(s)> <is/are> já está definido para a velocidade máxima.
  • minSettingReached : <device(s)> <is/are> já está definido para a configuração mais baixa.
  • minSpeedReached : <device(s)> <is/are> já está definido para a velocidade mínima.
  • monitoringServiceConnectionLost : <device(s)> <has/have> perdeu <its/their> conexão com o serviço de monitoramento.
  • needAttachment : Parece que <device(s)> <is/are> está sem um anexo obrigatório. Substitua e tente novamente.
  • needBin : Parece que <device(s)> <is/are> não tem um recipiente. Substitua e tente novamente.
  • needPads : <device(s)> <need(s)> novos pads.
  • needSoftwareUpdate : <device(s)> <need(s)> uma atualização de software.
  • precisa de água : <device(s)> <need(s)> água.
  • networkProfileNotRecognized : Não reconheço "<network profile>" em <device(s)>.
  • networkSpeedTestInProgress : já estou testando <network> <speed/speeds>>.
  • noAvailableApp : Parece que <nome do app> não está disponível.
  • noAvailableChannel : Parece que o canal <channel name> não está disponível.
  • noChannelSubscription : Você não está inscrito no canal <nome do canal> no momento.
  • noTimerExists : Parece que não há nenhum timer definido em <device(s)>.
  • notSupported : Esse modo não está disponível para <device(s)>.
  • obstructionDetected : <dispositivo(s)> detectou uma obstrução.
  • offline , deviceOff-line : Parece que <device(s)> <is/are> não está disponível no momento.
  • onRequiresMode : especifique qual modo você quer ativar.
  • senha concluída : Parece que o PIN está incorreto.
  • percentOutOfRange : Não é possível definir <device(s)> como <percent>.
  • pinIncorreto : (senha incorreta)
  • rainDetected : Não abri o <device(s)> porque foi detectado chuva.
  • rangeTooClose : essas são muito próximas para um intervalo aquecer/resfriar para <device(s)>. Escolha temperaturas mais distantes entre si.
  • relinkRequired : Parece que algo deu errado com sua conta. Use o app Google Home ou Google Assistente para vincular <device(s)> novamente.
  • RemoteSetDisabled :
    • Parâmetro opcional errorCodeReason
    • currentlyArmed - Como o sistema de segurança já está ligado, você precisa usar <device(s)> ou o aplicativo para fazer alterações.
    • remoteUnlockNotAllowed - Não consigo desbloquear <dispositivo(s)> remotamente.
    • remoteControlOff: esta ação está desativada no momento. Ative o controle remoto em <device(s)> e tente de novo.
    • childSafetyModeActive: essa ação vai ficar desativada nos <dispositivo(s)> enquanto o modo de segurança infantil estiver ativo.
  • roomOnDifferentFloors : <device(s)> não pode acessar esses ambientes porque eles estão em andares diferentes.
  • safetyShutOff : <dispositivos> <estão/estão> no modo de desligamento de segurança, portanto, <it/eles> precisam ser ajustados manualmente.
  • sceneCannotBeApplied : Não foi possível aplicar <device(s)>.
  • securityRestriction : <dispositivos> <tem/têm> uma restrição de segurança.
  • softwareUpdateNotAvailable : Não há atualização de software disponível nos dispositivos <device(s)>.
  • startRequiresTime : Para fazer isso, você precisa me dizer por quanto tempo você quer executar <device(s)>.
  • stillCoolingDown : <dispositivo(s)> <está/estão> ainda está resfriando.
  • stillWarmingUp : <dispositivo(s)> <está/estão> ainda aquecendo.
  • streamAvailable : Parece que a transmissão não está disponível em <device(s)>.
  • streamUnplayable : Não consigo abrir a transmissão em <device(s)> no momento.
  • tankEmpty : <dispositivo(s)> <tem/têm> <tanques vazios/tanques vazios>. Encha <it/them> e tente novamente.
  • targetAlreadyReached : Parece que essa já é a temperatura atual.
  • timerValueOutOfRange : Não é possível definir <device(s)> nesse período.
  • Too ManyFailedAttempts : Muitas tentativas falharam. Acesse o app do dispositivo para concluir essa ação.
  • transientError : Ocorreu um erro ao controlar <device(s)>. Tente novamente.
  • desligado , deviceDesligado : <dispositivos> <estão/estão> desligados no momento.
  • errorToLocateDevice : Não consegui localizar <device(s)>.
  • UnknownFoodPreset : <device(s)> não é compatível com essa predefinição de alimento.
  • UnlockFailure : Não foi possível desbloquear <dispositivo(s)>.
  • unpausebleState : Não é possível pausar <device(s)> no momento.
  • userCancelada : ok
  • valueOutOfRange : Não é possível definir <device(s)> para essa temperatura.

Exceções

Retorne uma exceção quando houver um problema ou alerta associado a um comando. O comando pode ser bem-sucedido ou falhar.

Se o comando for bem-sucedido (status = "SUCCESS"), reporte exceções usando a característica StatusReport (para dispositivos diferentes do destino) ou retornando um exceptionCode apropriado (para o dispositivo de destino).

Por exemplo, se a tela do lint da secadora estiver cheia, o usuário ainda poderá ligar a secadora, mas você pode querer avisá-lo sobre esse estado. Da mesma forma, quando um dispositivo tem uma bateria fraca que não está vazia, você ainda pode executar um comando, mas precisa informar que a bateria do dispositivo está fraca.

Se o comando falhar devido a exceções, o status precisará ser "EXCEPTIONS" e as exceções precisarão ser informadas usando a característica StatusReport.

Exceção sem bloqueio (SUCCESS) sobre o dispositivo de destino

Este exemplo é para trancar a porta:

A bateria da fechadura da porta da frente está fraca. Trancando a porta da frente.

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

Exceção sem bloqueio (SUCCESS) sobre outro dispositivo usando o StatusReport

Este exemplo é para ligar um sistema de segurança: Ok, ligar o sistema de segurança. A janela da frente está aberta.

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

Exceção de bloqueio sobre outro dispositivo usando o 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"
          }
        ]
      }
    }
  }
}

Lista de exceções

As exceções abaixo vão produzir a TTS associada no dispositivo.

  • bagFull : <dispositivo(s)> <tem/tem> <saco cheio/malas cheias>. Esvazie <it/them> e tente novamente.
  • binFull : <dispositivo(s)> <tem/tem> <uma lixeira/compartimento cheio(s)>.
  • carbonMonoxideDetected : monóxido de carbono foi detectado em <nome da casa>.
  • deviceAtExtremeTemperatura : <device(s)> <is/are> a <uma temperatura extrema/temperaturas extremas>.
  • deviceJammingDetected : <dispositivo(s)> <está/estão> emperrado.
  • devicemóvel : <dispositivos> <foi/foram> movidos.
  • deviceOpen : <dispositivos> <está/estão> abertos.
  • deviceTampered : <dispositivos> <foram> adulterados.
  • deviceUnplugged : <dispositivos> <está/estão> desconectados.
  • floorUnreachable : <device(s)> não consegue chegar a esse ambiente. Coloque <ele/deles> no andar certo e tente de novo.
  • hardwareFailure : <dispositivo(s)> <tem/tem> um problema de hardware.
  • inSoftwareUpdate : <dispositivo(s)> <está/estão> em uma atualização de software.
  • isBypassed : <dispositivo(s)> <é/são> ignorado(s).
  • Bateria fraca : <dispositivos> <tem/têm> bateria fraca.
  • motionDetected : <dispositivo(s)> <detect(s)> movimento.
  • needPads : <device(s)> <need(s)> novos pads.
  • needSoftwareUpdate : <device(s)> <need(s)> uma atualização de software.
  • precisa de água : <device(s)> <need(s)> água.
  • networkJammingDetected : a conexão de rede doméstica com <device(s)> não está funcionando corretamente.
  • noIssuesReported : <device(s)> não informou problemas.
  • roomOnDifferentFloors : <device(s)> não pode acessar esses ambientes porque eles estão em andares diferentes.
  • runCycleConcluído : <device(s)> <tem/have> terminou de funcionar.
  • securityRestriction : <dispositivos> <tem/têm> uma restrição de segurança.
  • fumaçaDetected : fumaça foi detectada em <nome da casa>.
  • tankEmpty : <dispositivo(s)> <tem/têm> <tanques vazios/tanques vazios>. Encha <it/them> e tente novamente.
  • usingCellularBackup : <dispositivos> <está/estão> usando o backup celular.
  • waterLeakDetected : <dispositivo(s)> <detect(s)> um vazamento de água.