Compartilhar via

Entender 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á visualizar o erro 400027 ConnectionForcefullyClosedOnNewConnection se o dispositivo se desconectar e relatar 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 nova 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, verifique se cada cliente se conecta ao Hub IoT usando sua própria identidade.

401003 Hub IoT não autorizado

Nos logs, você poderá visualizar um padrão de dispositivos desconectando-se com 401003 IoTHubUnauthorized, seguido por 404104 DeviceConnectionClosedRemotelye, em seguida, conectando-se com êxito logo depois.

Ou, as solicitações para o 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 '*'
  • A regra de autorização '*' não permite acesso para '*'
  • Falha na autenticação deste dispositivo, renovação de token ou certificado e reconexão
  • A impressão digital não corresponde à configuração: Impressão digital: SHA1Hash=*, SHA2Hash=*; Configuração: ImpressãoDigitalPrimária=*, ImpressãoDigitalSecundária=*
  • 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. So:

  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, a regra ou a chave de autenticação. Esse resultado pode ser devido a qualquer uma das razões citadas nos sintomas.

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

O tempo de vida do token padrão é de 60 minutos entre SDKs; no entanto, para alguns SDKs, o tempo de vida 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 do token diferem para cada SDK. Para saber mais e obter informações sobre como determinar qual SDK seu dispositivo está usando em logs, consulte a seção sobre o comportamento de desconexão do dispositivo MQTT com os SDKs do Azure IoT, em Monitorar, diagnosticar e solucionar problemas de conectividade de dispositivo do Hub IoT 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 algum motivo, você não tiver acesso aos detalhes da mensagem de erro, verifique:

  • O token SAS ou outro token de segurança que você usa não expirou.
  • 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 no Hub IoT, consulte Tutorial: Criar e carregar certificados para teste.
  • Para autenticação de impressão digital do certificado X.509, a impressão digital do certificado do dispositivo é registrada no Hub IoT.
  • A credencial de autorização é bem formada para o protocolo que você usa. Para saber mais, confira Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra.
  • 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 "principal...", esse erro pode ser resolvido atribuindo o nível correto da permissão RBAC do Azure ao usuário. 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. Tente essa função para resolver o problema de falta de permissão.

Observação

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

Muitas vezes, executar uma sincronização de tempo usando NTP ou reinicializar 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 diariamente, semanalmente ou mensalmente, dependendo da quantidade de descompasso das experiências do dispositivo. Se você não puder configurar uma sincronização NTP periódica em seu dispositivo, agende uma reinicialização periódica.

403002 Hub IoT cota excedida

Talvez você veja 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.

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

Um trabalho de importação em massa também pode retornar esse erro quando o número de dispositivos registrados no hub IoT se aproxima ou excede o limite de cota para um hub IoT. Para saber mais, consulte a seção Solucionar problemas de trabalhos de importação do documento Importação e exportação em massa de identidades de dispositivo do Hub IoT.

403004 Profundidade máxima da fila do dispositivo excedida

Ao tentar enviar uma mensagem de 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 de nuvem para dispositivo com HTTPS é 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 para mensagens do tipo 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. Para obter mais informações, consulte a seção Expiração da mensagem (vida útil) de Noções básicas sobre mensagens de nuvem para dispositivo de um hub IoT.

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

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

Você pode ver que sua solicitação de upload de arquivo falha com o código de erro 403006 DeviceMaximumActiveFileUploadLimitExceeded e uma mensagem "O número de solicitações de upload de arquivo ativo não pode exceder 10".

Esse erro ocorre porque cada cliente de dispositivo é limitado para uploads de arquivos simultâneos. Você pode facilmente exceder o limite se o dispositivo não notificar o Hub IoT quando os uploads de arquivo forem concluídos. Uma rede do lado do dispositivo não confiável geralmente causa esse problema.

Para resolver esse erro, verifique se o dispositivo pode notificar prontamente a conclusão do upload 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ê poderá visualizar que a operação falha com o erro 404001 DeviceNotFound.

A operação falhou porque o 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 se o dispositivo estiver 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 obter mais informações sobre como configurar seu dispositivo corretamente para métodos diretos, consulte a seção Manipular um método direto em um dispositivo de Manipular um método direto em um dispositivo.

404104 Conexão do dispositivo fechada remotamente

Você pode ver que os dispositivos se desconectam em um intervalo regular (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 bem-sucedido menos de um minuto depois.

Ou, os dispositivos se desconectam aleatoriamente e você vê 404104 DeviceConnectionClosedRemotely nos 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, o que faz com que o Hub IoT desconecte o dispositivo. A conexão é restabelecida quando o dispositivo atualiza o token. Por exemplo, o token SAS expira a cada hora por padrão para o SDK C, o que pode levar a desconexões regulares. Para saber mais, consulte 401003 IoTHubUnauthorized.

Algumas outras possibilidades incluem:

  • O dispositivo perdeu a conectividade de rede subjacente por mais tempo do que o keep alive de 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 de nível TCP/IP, mas não enviou um nível MQTT DISCONNECTde aplicativo. Basicamente, o dispositivo fechou abruptamente a conexão de soquete subjacente. Às vezes, bugs em versões mais antigas do SDK do IoT do Azure podem causar esse problema.
  • O aplicativo do lado do dispositivo falhou.

Ou, o Hub IoT pode estar enfrentando um problema transitório. Para obter mais informações, consulte 500xxxx Erros internos.

Para resolver esse erro:

Observação

Recomendamos usar os SDKs do dispositivo IoT do Azure para gerenciar conexões de forma confiável. Para saber mais, confira Gerenciar reconexões de dispositivo para criar aplicativos resilientes

409001 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 do dispositivo no Hub IoT.

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

Você pode ver o erro 409002 LinkCreationConflict nos logs, juntamente com a desconexão do dispositivo ou a falha no envio 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 em log.

Ou, uma lógica defeituosa no lado do dispositivo faz com que o dispositivo estabeleça a conexão mesmo quando uma já está aberta.

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

412002 Bloqueio de mensagens do dispositivo

Ao tentar enviar uma mensagem de 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 de nuvem para dispositivo da fila (por exemplo, usando ReceiveAsync()), o Hub IoT bloqueia a mensagem por um tempo limite de bloqueio de um minuto. Se o dispositivo tentar concluir a mensagem depois que o tempo limite de bloqueio expirar, o Hub IoT gerará essa exceção.

Se o Hub IoT não receber a notificação dentro da duração do tempo limite de bloqueio de um minuto, ele definirá a mensagem de volta para o estado Enfileirado. 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 o recebimento da mensagem. Esse tempo limite de um minuto não pode ser alterado.

Exceção de limitação 429xxx

Você pode ver que suas solicitações para o Hub IoT falham com um erro que começa com 429 , como:

  • 429000 - Solicitações Genéricas em Excesso
  • 429001 – ThrottlingException: os Limites de limitação são excedidos para a operação solicitada.
  • 429002 – ThrottleBacklogLimitExceeded: o número de solicitações que estão na lista de pendências devido à limitação excedeu o limite de lista de pendências.
  • 429003 - ThrottlingBacklogTimeout: as solicitações que foram registradas novamente devido à limitação têm tempo limite enquanto aguardam na lista de pendências.
  • 429004 – ThrottlingMaxActiveJobCountExceeded
  • 429005 – DeviceThrottlingLimitExceeded

Você só pode monitorar 429001 por meio do Azure Monitor na métrica Número de Erros de Limitação. Atualmente, os outros erros de limitação não têm uma métrica associada, mas são capturados nos logs.

Para resolver esses erros, verifique se você está atingindo o limite de limitação comparando sua métrica de tentativas de envio de mensagem de telemetria com os limites especificados anteriormente. Você também pode verificar a métrica Número de erros de limitação. Para obter informações sobre essas métricas, consulte as métricas de telemetria do dispositivo. Para obter informações sobre como usar métricas para ajudá-lo a monitorar o hub IoT, consulte Monitorar o Hub IoT do Azure.

O Hub IoT retorna 429001 – ThrottlingException somente depois que o limite é violado por um período muito longo. Esse atraso ocorre 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 obter mais informações, consulte a seção Formatação de tráfego de cotas e limitação do IoT Hub.

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

Erros internos 500xxx

Você pode ver que sua solicitação para o 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 (sem código de erro): o Hub IoT encontrou um erro interno.

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

Pode haver muitas causas para uma resposta de erro 500xxx. Em todos os casos, o problema provavelmente é transitório. Embora a equipe do Hub IoT trabalhe duro para manter o SLA, pequenos subconjuntos de nós do Hub IoT podem ocasionalmente sofrer falhas transitórias. Quando o dispositivo tenta se conectar a um nó que está tendo problemas, você recebe esse erro.

Para atenuar erros 500xxx, emita uma nova tentativa do dispositivo. Para gerenciar tentativas automaticamente, use a versão mais recente dos SDKs do Hub IoT do Azure. Para obter mais informações sobre as práticas recomendadas para tratamento e repetições transitórias de falhas, consulte o tratamento transitório de falhas.

Se o problema persistir, verifique o Resource Health e o Status do Azure para ver se o Hub IoT tem um problema conhecido. Você também pode usar a função de failover manual.

Se não houver problemas conhecidos e o problema continuar, entre em contato com o suporte para uma investigação mais aprofundada.

503003 Partição não encontrada

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

Esse erro é interno para o Hub IoT e provavelmente é transitório. Para obter mais informações, consulte 500xxxx Erros internos.

Para resolver esse erro, consulte erros internos 500xxx.

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 do tempo limite. Ou, ao usar uma versão anterior do SDK do C# do Azure IoT (<1.19.0), o link AMQP entre o dispositivo e o Hub IoT pode ser descartado silenciosamente devido a um bug.

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

  • Last updated on