Compreender e resolver erros do Hub IoT do Azure

  • Artigo

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

400027 Conexão fechada com força em nova conexão

Você poderá ver 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, sua operação de gêmeo de dispositivo para nuvem (como propriedades de leitura ou relatório de patch) ou invocação direta do método 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, para que o Hub IoT feche a conexão anterior. O Hub IoT não permite que mais de um cliente se conecte utilizando a mesma identidade.

Para resolver esse erro, certifique-se de que cada cliente se conecte 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, em seguida, conectando-se com êxito pouco depois.

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

  • Cabeçalho de autorização ausente
  • IotHub '*' não contém o dispositivo especificado '*'
  • A regra de autorização '*' não permite o acesso a '*'
  • Falha na autenticação para este dispositivo, renovar token ou certificado e reconectar
  • A impressão digital não corresponde à configuração: Impressão digital: SHA1Hash=*, SHA2Hash=*; Configuração: PrimaryThumbprint=*, SecondaryThumbprint=*
  • Principal user@example.com não está autorizado para GET on /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. Desta forma,

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

Ou, o Hub IoT não conseguiu autenticar o cabeçalho, a regra ou a chave de autenticação. Isso 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 da IoT para conexão usando a cadeia de conexão do dispositivo. O IoT SDK regenera o novo token para se reconectar na expiração do token SAS.

A vida útil padrão do token é 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 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 Comportamento de desconexão de dispositivo MQTT com SDKs do Azure IoT.

Para desenvolvedores de dispositivos, se o volume de erros for uma preocupação, alterne para o C SDK, 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, certifique-se de:

  • A SAS ou outro token de segurança que você usa não expirou.
  • Para autenticação de certificado X.509, o certificado do dispositivo ou o certificado da autoridade de certificação associado ao dispositivo não expirou. Para saber como registrar certificados de CA X.509 com o 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 está bem formada para o protocolo que você usa. Para saber mais, consulte 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 "principal...", esse erro pode ser resolvido atribuindo o nível correto da permissão do Azure RBAC ao usuário. Por exemplo, um Proprietário no Hub IoT pode atribuir a função "Proprietário de Dados do Hub IoT", que concede todas as permissões. Tente esta função para resolver o problema de falta de permissão.

Nota

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

Muitas vezes, executar uma sincronização de tempo usando NTP ou reiniciar 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 diariamente, semanalmente ou mensalmente, dependendo da quantidade de desvio que o dispositivo experimenta. Se não for possível configurar uma sincronização NTP periódica no dispositivo, agende uma reinicialização periódica.

403002 cota do Hub IoT excedida

Você pode ver 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 carrega.

Esse erro normalmente ocorre quando a cota diária de mensagens para o hub IoT é excedida. Para resolver este erro:

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 para um hub IoT. Para saber mais, consulte Solucionar problemas de trabalhos de importação.

403004 Profundidade máxima da fila do dispositivo excedida

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

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

A razão mais provável pela qual você está atingindo esse limite é porque está usando HTTPS para receber a mensagem, o que leva à sondagem contínua usando ReceiveAsync, resultando na limitação da solicitação pelo Hub IoT.

O padrão suportado para mensagens da nuvem para o dispositivo com 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 entrar no limite da fila, mude para AMQP ou MQTT para mensagens da nuvem para o dispositivo.

Como alternativa, aprimore a lógica do lado do dispositivo para completar, rejeitar ou abandonar mensagens em fila rapidamente, reduzir o tempo de vida ou considerar o envio de menos mensagens. Veja Vida útil das mensagens C2D.

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

403006 Limite máximo de upload de arquivos ativos do dispositivo excedido

Poderá ver que o seu pedido de carregamento de ficheiros falha com o código de erro 403006 DeviceMaximumActiveFileUploadLimitExceeded e uma mensagem "O número de pedidos de carregamento de ficheiros ativos não pode exceder 10".

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

Para resolver esse erro, certifique-se de que o dispositivo possa notificar imediatamente a conclusão do carregamento do arquivo do Hub IoT. Em seguida, tente reduzir o TTL do token SAS para a configuração de upload de arquivos.

404001 dispositivo não encontrado

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

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

Para resolver este erro, registe o ID do dispositivo que utilizou e, em seguida, tente novamente.

404103 dispositivo não está 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ê sabe que o dispositivo está online e ainda recebe o erro, então o erro provavelmente ocorreu porque o retorno de chamada do método direto não está registrado no dispositivo.

Para configurar seu 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 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ê uma queda na métrica Dispositivos conectados (connectedDeviceCount) e há mais erros internos 404104 DeviceConnectionClosedRemotely e 500xxx nos 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 token é atualizado pelo dispositivo. Por exemplo, o token SAS expira a cada hora por padrão para o C SDK, 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 MQTT keep-alive, resultando em um tempo limite de ociosidade remoto. A configuração keep-alive MQTT pode ser diferente por dispositivo.
  • O dispositivo enviou uma redefinição de nível TCP/IP, mas não enviou uma redefinição de nível MQTT DISCONNECTde aplicativo. Basicamente, o dispositivo fechou abruptamente a conexão de soquete subjacente. Às vezes, esse problema é causado por bugs em versões mais antigas do SDK do Azure IoT.
  • O aplicativo do lado do dispositivo travou.

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

Para resolver este erro:

  • Consulte as orientações para erro 401003 IoTHubUnauthorized.
  • Verifique se o dispositivo tem boa conectividade com o Hub IoT testando a conexão. Se a rede não for confiável ou intermitente, não recomendamos aumentar o valor de keep-alive porque isso pode resultar em uma deteção (por meio de alertas do Azure Monitor, por exemplo) demorando mais.
  • Use as versões mais recentes dos SDKs de IoT.
  • Consulte as orientações para erros do servidor interno do Hub IoT.

Recomendamos utilizar SDKs de dispositivo IoT do Azure para gerir conexões de forma confiável. Para saber mais, consulte Gerir a conetividade e as mensagens fiáveis utilizando os SDKs de dispositivo do Azure IoT Hub

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.

Este erro ocorre porque já existe um dispositivo com o mesmo ID de dispositivo no hub IoT.

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

Você pode ver o erro 409002 LinkCreationConflict em logs, juntamente com desconexão do dispositivo ou falha de mensagem de nuvem para dispositivo.

Geralmente, esse erro acontece quando o Hub IoT deteta 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 defeituosa do lado do dispositivo faz com que o dispositivo estabeleça a conexão quando uma já está aberta.

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 somente se a conexão cair.

412002 Bloqueio de mensagem do dispositivo perdido

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

Este erro ocorre porque quando um dispositivo recebe uma mensagem de nuvem para dispositivo da fila (por exemplo, usando ReceiveAsync()) a mensagem é bloqueada pelo Hub IoT 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 lançará 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 ao estado Enfileirado . O dispositivo pode tentar receber a mensagem novamente. Para evitar que o erro aconteça no futuro, implemente a lógica do lado do dispositivo para concluir a mensagem dentro de um minuto após o recebimento da mensagem. Este tempo limite de um minuto não pode ser alterado.

429001 Exceção de limitação

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

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

Para resolver esse erro, verifique se você está atingindo o limite de limitação comparando a 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, consulte Métricas de telemetria de dispositivo. Para obter informações sobre como usar métricas para ajudá-lo a monitorar seu hub IoT, consulte Monitorar o Hub IoT.

O Hub IoT retorna 429 ThrottlingException somente depois que o limite foi violado por um período muito longo. Isso é feito para que suas mensagens não sejam descartadas se o hub IoT receber tráfego de intermitência. Entretanto, o Hub IoT processa as mensagens de acordo com a velocidade de acelerador da operação, que pode ser lenta caso haja demasiado tráfego no registo de tarefas pendentes. Para saber mais, veja Modelagem de tráfego do Hub IoT.

Considere a possibilidade de aumentar verticalmente o Hub IoT se estiver a atingir os limites de quota ou de limitação.

Erros internos 500xxx

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 do servidor". Algumas possibilidades são:

  • 500001 ServerError: O Hub IoT teve um problema no 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. Enquanto a equipe do Hub IoT trabalha duro para manter o SLA, pequenos subconjuntos de nós do Hub IoT podem, ocasionalmente, experimentar falhas transitórias. Quando o dispositivo tenta se conectar a um nó que está tendo problemas, você recebe esse erro.

Para atenuar os erros 500xxx, execute uma nova tentativa a partir do dispositivo. Para gerenciar automaticamente as tentativas, certifique-se de usar a versão mais recente dos SDKs do Azure IoT. Para obter as melhores práticas sobre tratamento e tentativas de falhas transitórias, consulte Tratamento de falhas transitórias.

Se o problema persistir, verifique a Integridade do Recurso e o Status do Azure para ver se o Hub IoT tem um problema conhecido. Você também pode usar o recurso 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.

Este erro é interno ao Hub IoT e provavelmente é transitório. Consulte Erros internos do servidor do Hub IoT.

Para resolver esse erro, consulte Erros internos do servidor 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.

Este 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 Azure IoT C# SDK (<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, tente novamente ou atualize para a versão mais recente do SDK do Azure IOT C#.