Obter noções básicas e resolver erros do Hub IoT do Azure

Este artigo descreve as causas e soluções para códigos de erro comuns que você pode encontrar ao usar o Hub IoT.

Conexão 400027 fortemente fechada em uma nova conexão

Você poderá ver o erro 400027 ConnectionForcefullyClosedOnNewConnection se seu dispositivo se desconectar e informar Communication_Error como ConnectionStatusChangeReason usando o SDK do .NET e o tipo de transporte MQTT. Ou, a operação gêmea do dispositivo para a nuvem (como por exemplo, propriedades relatadas de leitura ou patch) ou a invocação do método direto falha com o código de erro 400027.

Esse erro ocorre quando outro cliente cria uma conexão com o Hub IoT usando a mesma identidade, portanto, o Hub IoT fecha a conexão anterior. O Hub IoT não permite que mais de um cliente se conecte usando a mesma identidade.

Para resolver esse erro, confira se cada cliente está conectando ao Hub IoT usando sua própria identidade.

401003 Hub IoT não autorizado

Nos logs, você pode ver um padrão de dispositivos se desconectando com 401003 IoTHubUnauthorized, seguido por 404104 DeviceConnectionClosedRemotely e depois se conectando com êxito logo em seguida.

Ou, as solicitações ao Hub IoT falham com uma das seguintes mensagens de erro:

• Cabeçalho de autorização ausente
• O IotHub '*' não contém o dispositivo especificado '*'
• Regra de autorização '*' não permite acesso para '*'
• Falha de autenticação para este dispositivo, renovar o token ou certificado e reconectar
• A impressão digital não corresponde à configuração: Impressão digital: SHA1Hash=*, SHA2Hash=*; Configuração: PrimaryThumbprint=*, SecondaryThumbprint=*
• A user@example.com entidade de segurança não está autorizada para GET em /exampleOperation devido a nenhuma permissão atribuída

Esse erro ocorre porque para MQTT, alguns SDKs dependem do Hub IoT para emitir a desconexão quando o token SAS expira para saber quando atualizá-lo. Portanto,

1. O token SAS expira
2. O Hub IoT observa a expiração e desconecta o dispositivo com 401003 IoTHubUnauthorized
3. O dispositivo conclui a desconexão com 404104 DeviceConnectionClosedRemotely
4. O SDK do IoT gera um novo token SAS
5. O dispositivo se reconecta com o Hub IoT com êxito

Ou, o Hub IoT não pôde autenticar o cabeçalho de autenticação, a regra ou a chave. Isso pode ser devido a qualquer um dos motivos citados nos sintomas.

Para resolver esse erro, não é necessária nenhuma ação se estiver usando o SDK do IoT para conexão usando a cadeia de conexão de dispositivo. O SDK do IoT regenera o novo token para se reconectar na expiração do token SAS.

A vida útil do token padrão é de 60 minutos entre SDKs; no entanto, para alguns SDKs, a vida útil do token e o limite de renovação do token são configuráveis. Além disso, os erros gerados quando um dispositivo se desconecta e se reconecta na renovação de token são diferentes para cada SDK. Para saber mais e obter informações sobre como determinar qual SDK seu dispositivo está usando nos logs, consulte o comportamento de desconexão de dispositivo MQTT com SDKs da Internet das Coisas do Azure.

Para desenvolvedores de dispositivos, se o volume de erros for uma preocupação, alterne para o SDK do C, que renova o token SAS antes da expiração. Para AMQP, o token SAS pode ser atualizado sem desconexão.

Em geral, a mensagem de erro apresentada deve explicar como corrigir o erro. Se, por alguma razão, você não tiver acesso aos detalhes da mensagem de erro, verifique se:

• O token SAS ou outro token de segurança usado não esteja expirado.
• Para a autenticação de certificado X.509, o certificado de dispositivo ou o certificado de autoridade de certificação associado ao dispositivo não fica expirado. Para saber como registrar certificados de autoridade de certificação X.509 com o Hub IoT, consulte Tutorial: Criar e carregar certificados para teste.
• Para a autenticação de impressão digital do certificado X 509, a impressão digital do certificado do dispositivo é registrada com o Hub IoT.
• A credencial de autorização está bem formada para o protocolo que você usa. Para saber mais, confira Controlar o acesso ao Hub IoT.
• A regra de autorização usada tem a permissão para a operação solicitada.
• Para as últimas mensagens de erro que começam com "entidade de segurança...", esse erro pode ser resolvido atribuindo ao usuário o nível correto de permissão RBAC do Azure. Por exemplo, um Proprietário no Hub IoT pode atribuir a função "Proprietário de Dados do Hub IoT", que fornece todas as permissões. Experimente essa função para resolver o problema da falta de permissão.

Observação

Alguns dispositivos podem enfrentar um problema de descompasso de tempo quando a hora do dispositivo tem uma diferença de mais de cinco minutos em relação ao servidor. Esse erro pode ocorrer quando um dispositivo está se conectando a um hub IoT sem problemas há semanas, ou até mesmo meses, mas começa a ter sua conexão recusada continuamente. O erro também pode ser específico a um subconjunto de dispositivos conectados ao hub IoT, pois o descompasso de tempo pode ocorrer em taxas diferentes dependendo de quando um dispositivo é conectado ou ativado pela primeira vez.

Muitas vezes, executar uma sincronização de tempo usando NTP ou reinicializando o dispositivo (que pode executar automaticamente uma sincronização de tempo durante a sequência de inicialização) corrige o problema e permite que o dispositivo se conecte novamente. Para evitar esse erro, configure o dispositivo para executar uma sincronização de tempo periódica usando NTP. Você pode agendar a sincronização para que seja diária, semanal ou mensal dependendo de quanto descompasso o dispositivo apresenta. Se você não puder configurar uma sincronização NTP periódica no dispositivo, agende uma reinicialização periódica.

403002 Hub IoT cota excedida

Você pode ver as solicitações para o Hub IoT falharem com o erro 403002 IoTHubQuotaExceeded. E no portal do Azure, a lista de dispositivos do Hub IoT não é carregada.

Geralmente, esse erro ocorre quando a cota de mensagens diárias para o Hub IoT é excedida. Para resolver esse erro:

• Atualize ou aumente o número de unidades no Hub IoT ou aguarde o próximo dia UTC para que a cota diária seja atualizada.
• Para entender como as operações são contadas para a cota, como consultas de gêmeos e métodos diretos, confira Noções básicas dos preços do Hub IoT.
• Para configurar o monitoramento do uso diário da cota, configurar um alerta com a métrica Número total de mensagens usadas. Para obter instruções passo a passo, consulte Configurar métricas e alertas com o Hub IoT.

Esse erro também pode ser retornado por um trabalho de importação em massa, quando o número de dispositivos registrados no hub IoT se aproxima ou excede o limite de cota de um hub IoT. Para saber mais, confira Solucionar problemas nos trabalhos de importação.

403004 Profundidade máxima da fila do dispositivo excedida

Ao tentar enviar uma mensagem da nuvem para dispositivo, você pode ver que a solicitação falha com o erro 403004 ou DeviceMaximumQueueDepthExceeded.

A causa subjacente desse erro é que o número de mensagens enfileiradas para o dispositivo excede o limite de fila .

O motivo mais provável pelo qual está atingindo esse limite é porque você está usando HTTPS para receber a mensagem, o que causa um pool contínuo usando ReceiveAsync, resultando na limitação do Hub IoT à solicitação.

O padrão com suporte para mensagens da nuvem para o dispositivo com o HTTPS são dispositivos conectados intermitentemente que verificam mensagens com pouca frequência (menos do que a cada 25 minutos). Para reduzir a probabilidade de atingir o limite da fila, alterne para AMQP ou MQTT as mensagens da nuvem para dispositivo.

Como alternativa, aprimore a lógica do lado do dispositivo para concluir, rejeitar ou abandonar mensagens em fila imediatamente, encurte o tempo de vida ou então considere enviar menos mensagens. Consulte vida útil da mensagem C2D.

Por fim, considere usar a API Limpar Fila para limpar periodicamente as mensagens pendentes antes que o limite seja atingido.

403006 Limite máximo de carregamento do arquivo ativo do dispositivo excedido

Talvez você veja que a solicitação de carregamento do arquivo falhou com o código de erro 403006 DeviceMaximumActiveFileUploadLimitExceeded e a mensagem "O número de solicitações ativas de carregamento de arquivos não pode exceder 10".

Esse erro ocorre porque cada cliente do dispositivo é limitado para uploads de arquivos simultâneos. Você poderá exceder facilmente o limite se o dispositivo não notificar o Hub IoT quando os uploads de arquivos são concluídos. Esse problema geralmente é causado por uma rede do lado do dispositivo não confiável.

Para resolver esse erro, confira se o dispositivo pode prontamente notificar a conclusão de carregamento de arquivo do Hub IoT. Em seguida, tente reduzir o TTL do token SAS para a configuração de upload de arquivo.

404001 Dispositivo não encontrado

Durante uma comunicação de C2D (nuvem para dispositivo), como mensagem C2D, atualização de conexão ou método direto, você pode ver que a operação falha com o erro 404001 DeviceNotFound.

A operação falhou porque Hub IoT não consegue localizar o dispositivo. O dispositivo não está registrado ou está desabilitado.

Para resolver esse erro, registre a ID do dispositivo usada e tente novamente.

404103 Dispositivo não online

Você pode ver que um método direto para um dispositivo falha com o erro 404103 DeviceNotOnline mesmo que o dispositivo esteja online.

Se você souber que o dispositivo está online e ainda receber o erro, então o erro ocorreu provavelmente porque o retorno de chamada do método direto não está registrado no dispositivo.

Para configurar o dispositivo corretamente para retornos de chamada de método direto, consulte manipular um método direto em um dispositivo.

404104 Conexão do dispositivo fechada remotamente

Você pode ver que os dispositivos se desconectam em intervalos regulares (a cada 65 minutos, por exemplo) e você vê 404104 DeviceConnectionClosedRemotely nos logs de recursos do Hub IoT. Às vezes, você também vê 401003 IoTHubUnauthorized e um evento de conexão de dispositivo com êxito menos de um minuto depois.

Ou, os dispositivos se desconectam aleatoriamente e você vê 404104 DeviceConnectionClosedRemotely em logs de recursos do Hub IoT.

Ou, muitos dispositivos se desconectam ao mesmo tempo, você vê um queda na métrica de dispositivos conectados (connectedDeviceCount) e há mais erros 404104 DeviceConnectionClosedRemotely e 500xxx Internal errors em logs do Azure Monitor do que o normal.

Esse erro pode ocorrer porque o token SAS usado para se conectar ao Hub IoT expirou, fazendo com que o Hub IoT desconecte o dispositivo. A conexão é restabelecida quando o token é atualizado pelo dispositivo. Por exemplo, o token SAS expira a cada hora por padrão para o SDK do C, o que pode causar desconexões regulares. Para saber mais, confira a 401003 IoTHubUnauthorized.

Algumas outras possibilidades incluem:

• O dispositivo perdeu a conectividade de rede subjacente por mais tempo do que o keep alive MQTT, resultando em um tempo limite ocioso remoto. A configuração de keep alive MQTT pode ser diferente por dispositivo.
• O dispositivo enviou uma redefinição no nível de TCP/IP, mas não enviou um MQTT DISCONNECT no nível de aplicativo. Basicamente, o dispositivo fechou repentinamente a conexão de soquete subjacente. Às vezes, esse problema é causado por bugs em versões mais antigas do SDK do Internet das Coisas do Azure.
• O aplicativo no lado do dispositivo falhou.

Ou, o Hub IoT pode estar enfrentando um problema transitório. Consulte Erro de servidor interno do Hub IoT.

Para resolver esse erro:

• Consulte as diretrizes para o erro 401003 IoTHubUnauthorized.
• Certifique-se de que o dispositivo possa se conectar ao Hub IoT testando a conexão. Se a rede for não confiável ou intermitente, não é recomendável aumentar o valor keep-alive porque isso pode resultar em mais demora na detecção (via alertas do Azure Monitor alertas, por exemplo).
• Use as versões mais recentes dos SDKs de IoT.
• Consulte as diretrizes para Erros internos do servidor do Hub IoT.

Recomendamos usar os SDKs do dispositivo IoT do Azure para gerenciar conexões de forma confiável. Para saber mais, consulte Gerenciar a conectividade e as mensagens confiáveis usando SDKs do dispositivo do Hub IoT do Azure

409001 O dispositivo já existe

Ao tentar registrar um dispositivo no Hub IoT, você pode ver que a solicitação falha com o erro 409001 DeviceAlreadyExists.

Esse erro ocorre porque já existe um dispositivo com a mesma ID de dispositivo no Hub IoT.

Para resolver esse erro, use uma ID de dispositivo diferente e tente novamente.

409002 Conflito de criação do link

Você poderá ver o erro 409002 LinkCreationConflict nos logs, junto à desconexão do dispositivo ou a falha de mensagem da nuvem para o dispositivo.

Geralmente, esse erro ocorre quando o Hub IoT detecta que um cliente tem mais de uma conexão. Na verdade, quando uma nova solicitação de conexão chega para um dispositivo com uma conexão existente, o Hub IoT fecha a conexão existente com esse erro.

No caso mais comum, um problema separado (como 404104 DeviceConnectionClosedRemotely)faz com que o dispositivo se desconecte. O dispositivo tenta restabelecer a conexão imediatamente, mas o Hub IoT ainda considera o dispositivo conectado. O Hub IoT fecha a conexão anterior e registra esse erro.

Ou, a lógica do lado do dispositivo com falha faz com que o dispositivo estabeleça a conexão quando um já está aberto.

Para resolver esse erro, procure outros erros nos logs que você pode solucionar porque esse erro geralmente aparece como um efeito colateral de um problema diferente e transitório. Caso contrário, certifique-se de emitir uma nova solicitação de conexão apenas se a conexão cair.

412002 Bloqueio de mensagens do dispositivo

Ao tentar enviar uma mensagem da nuvem para dispositivo, você pode ver que a solicitação falha com o erro 412002 DeviceMessageLockLost.

Esse erro ocorre porque quando um dispositivo recebe uma mensagem da nuvem para o dispositivo da fila (por exemplo, usando ReceiveAsync()) a mensagem é bloqueada pelo Hub IoT por uma duração de tempo limite de bloqueio de um minuto. Se o dispositivo tentar concluir a mensagem após a expiração do tempo de bloqueio, o Hub IoT lançará essa exceção.

Se o Hub IoT não receber a notificação dentro da duração do tempo de bloqueio de um minuto, ele define a mensagem de volta para o estado Enqueued. O dispositivo pode tentar receber a mensagem novamente. Para evitar que o erro ocorra no futuro, implemente a lógica do lado do dispositivo para concluir a mensagem dentro de um minuto após receber a mensagem. Esse tempo-out de um minuto não pode ser alterado.

429001 Exceção da limitação

Você pode ver que suas solicitações ao Hub IoT falham com o erro 429001 ThrottlingException.

Esse erro ocorre quando os limites de limitação do Hub IoT foram excedidos para a operação solicitada.

Para resolver esse erro, confira se você está atingindo o limite de restrição comparando sua métrica de Tentativas de envio de mensagem de telemetria com os limites especificados acima. Você também pode verificar a métrica Número de erros de limitação. Para obter informações sobre essas métricas, confira Métricas de telemetria de dispositivo. Para obter informações sobre como usar métricas para ajudá-lo a monitorar o Hub IoT, consulte Monitorar o Hub IoT.

O Hub IoT retorna 429 ThrottlingException somente após o limite ter sido violado por um período muito longo. Isso é feito para que suas mensagens não sejam removidas se o Hub IoT obtiver tráfego intermitente. Enquanto isso, o Hub IoT processa as mensagens na taxa de limitação da operação, o que pode ser lento se houver muito tráfego na lista de pendências. Para saber mais, consulte modelagem de tráfego do Hub IoT.

Considere escalar verticalmente seu Hub IoT se você estiver chegando à cota ou limites de limitação.

500xxx Internal errors

Você pode ver que sua solicitação ao Hub IoT falha com um erro que começa com 500 e/ou algum tipo de "erro de servidor". Algumas possibilidades são:

• 500001 ServerError: o Hub IoT encontrou um problema no lado do servidor.

• 500008 GenericTimeout: o Hub IoT não pôde concluir a solicitação de conexão antes do tempo limite.

• ServiceUnavailable (nenhum código de erro) : o Hub IoT encontrou um erro interno.

• InternalServerError (nenhum código de erro) : o Hub IoT encontrou um erro interno.

Pode haver várias causas para uma resposta de erro 500xxx. Em todos os casos, é mais provável que o problema seja transitório. Enquanto a equipe do Hub IoT trabalha muito para manter o SLA, pequenos subconjuntos de nós do IoT Hub podem ocasionalmente sofrer falhas transitórias. Quando o dispositivo tenta se conectar a um nó com problemas, você recebe esse erro.

Para atenuar erros 500xxx, emita uma nova tentativa do dispositivo. Para gerenciar automaticamente as novas tentativas, certifique-se de usar a versão mais recente dos SDKs do Azure IoT. Como prática recomendada no tratamento de falhas transitórias e novas tentativas, consulte tratamento de falhas transitórias.

Se o problema persistir após várias tentativas, verifique Resource Health e Status do Azure para ver se o IoT Hub tem um problema conhecido. Você também pode usar o recurso de failover manual.

Se não houver nenhum problema conhecido e o problema persistir, entre em contato com o suporte para uma investigação adicional.

503003 Partição não encontrada

Você pode ver que as solicitações ao Hub IoT falham com o erro 503003 PartitionNotFound.

Esse erro é interno ao Hub IoT e, provavelmente, é transitório. Consulte Erros de servidor interno do Hub IoT.

Para resolver esse erro, consulte Erros de servidor interno do Hub IoT.

504101 Tempo limite do Gateway

Ao tentar invocar um método direto do Hub IoT para um dispositivo, você pode ver que a solicitação falha com o erro 504101 GatewayTimeout.

Esse erro ocorre porque o Hub IoT encontrou um erro e não pôde confirmar se o método direto foi concluído antes de atingir o tempo limite. Ou, ao usar uma versão anterior de C# do SDK do Azure IoT (<1.19.0), o link AMQP entre o dispositivo e Hub IoT pode ser removido silenciosamente devido a um bug.

Para resolver esse erro, emita uma nova tentativa ou atualização para a versão mais recente do C# do SDK do Azure IoT.