Partilhar via

Exceções de mensagens dos Hubs de Eventos - .NET (legado)

  • Artigo

Esta seção lista as exceções do .NET geradas pelas APIs do .NET Framework.

Importante

Algumas das exceções listadas no artigo aplicam-se apenas à biblioteca .NET dos Hubs de Eventos herdada. Por exemplo: exceções Microsoft.ServiceBus.*.

Para obter informações sobre o EventHubsException gerado pela nova biblioteca .NET, consulte EventHubsException - .NET

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Categorias de exceção

As APIs .NET dos Hubs de Eventos geram exceções que podem se enquadrar nas seguintes categorias, juntamente com a ação associada que você pode tomar para tentar corrigi-las:

Tipos de exceção

A tabela a seguir lista os tipos de exceção de mensagens e suas causas, além de anotar as ações sugeridas que você pode tomar.

Tipo de Exceção Descrição/Causa/Exemplos Ação sugerida Nota sobre a repetição automática/imediata
TimeoutException O servidor não respondeu à operação solicitada dentro do tempo especificado, que é controlado por OperationTimeout. O servidor pode ter concluído a operação solicitada. Esta exceção pode acontecer devido a atrasos na rede ou noutras infraestruturas. Verifique a consistência do estado do sistema e tente novamente, se necessário.
Consulte TimeoutException.		 Repetir pode ajudar em alguns casos; Adicione lógica de repetição ao código.
InvalidOperationException A operação de usuário solicitada não é permitida dentro do servidor ou serviço. Consulte a mensagem de exceção para obter detalhes. Por exemplo, Complete gera essa exceção se a mensagem foi recebida no modo ReceiveAndDelete . Verifique o código e a documentação. Verifique se a operação solicitada é válida. Repetir não vai ajudar.
OperationCanceledException É feita uma tentativa de invocar uma operação em um objeto que já foi fechado, abortado ou descartado. Em casos raros, a transação ambiental já está descartada. Verifique o código e certifique-se de que ele não invoque operações em um objeto descartado. Repetir não vai ajudar.
UnauthorizedAccessException O objeto TokenProvider não pôde adquirir um token, o token é inválido ou o token não contém as declarações necessárias para fazer a operação. Verifique se o provedor de token foi criado com os valores corretos. Verifique a configuração do Serviço de Controle de Acesso. Repetir pode ajudar em alguns casos; Adicione lógica de repetição ao código.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 Um ou mais argumentos fornecidos ao método são inválidos. O URI fornecido para NamespaceManager ou Create contém segmento(s) de caminho. O esquema de URI fornecido para NamespaceManager ou Create é inválido. O valor da propriedade é maior que 32 KB. Verifique o código de chamada e certifique-se de que os argumentos estão corretos. Repetir não ajudará.
Microsoft.ServiceBus.Messaging MessagingEntityNotFoundException

Microsoft.Azure.EventHubs MessagingEntityNotFoundException		 A entidade associada à operação não existe ou foi excluída. Certifique-se de que a entidade existe. Repetir não ajudará.
MensagemComunicaçãoExceção O cliente não consegue estabelecer uma conexão com Hubs de Eventos. Verifique se o nome do host fornecido está correto e se o host está acessível. Repetir pode ajudar se houver problemas intermitentes de conectividade.
Microsoft.ServiceBus.Messaging ServerBusyException

Microsoft.Azure.EventHubs ServerBusyException		 O serviço não é capaz de processar a solicitação no momento. O cliente pode esperar por um período de tempo e, em seguida, tentar novamente a operação.
Consulte ServerBusyException.		 O cliente pode tentar novamente após um determinado intervalo. Se uma nova tentativa resultar em uma exceção diferente, verifique o comportamento de repetição dessa exceção.
MessagingException Exceção de mensagens genéricas que pode ser lançada nos seguintes casos: É feita uma tentativa de criar um QueueClient usando um nome ou caminho que pertence a um tipo de entidade diferente (por exemplo, um tópico). É feita uma tentativa para enviar uma mensagem com mais de 1 MB. O servidor ou serviço encontrou um erro durante o processamento da solicitação. Consulte a mensagem de exceção para obter detalhes. Esta exceção é geralmente uma exceção transitória. Verifique o código e certifique-se de que apenas objetos serializáveis sejam usados para o corpo da mensagem (ou use um serializador personalizado). Verifique na documentação os tipos de valor suportados das propriedades e use apenas os tipos suportados. Verifique a propriedade IsTransient . Se for verdade, você pode tentar novamente a operação. O comportamento de repetição é indefinido e pode não ajudar.
MessagingEntityAlreadyExistsException Tente criar uma entidade com um nome que já seja usado por outra entidade nesse namespace de serviço. Exclua a entidade existente ou escolha um nome diferente para a entidade a ser criada. Repetir não ajudará.
QuotaExceededException A entidade de mensagens atingiu seu tamanho máximo permitido. Esta exceção pode acontecer se o número máximo de recetores (que é 5) já tiver sido aberto a nível de grupo de consumidores. Crie espaço na entidade recebendo mensagens da entidade ou de suas subfilas.
Consulte QuotaExceededException		 Repetir pode ajudar se as mensagens tiverem sido removidas entretanto.
MessagingEntityDisabledException Solicitação de uma operação de tempo de execução em uma entidade desabilitada. Ative a entidade. Repetir pode ajudar se a entidade tiver sido ativada nesse ínterim.
Microsoft.ServiceBus.Messaging MessageSizeExceededException

Microsoft.Azure.EventHubs MessageSizeExceededException		 Uma carga útil de mensagem excede o limite de 1 MB. Esse limite de 1 MB é para a mensagem total, que pode incluir propriedades do sistema e qualquer sobrecarga do .NET. Reduza o tamanho da carga útil da mensagem e, em seguida, tente novamente a operação. Repetir não ajudará.

QuotaExceededException

QuotaExceededException indica que foi excedida uma quota de uma entidade específica.

Esta exceção pode ocorrer se o número máximo de recetores (5) já tiver sido aberto a nível de grupo de consumidores.

Event Hubs

Os Hubs de Eventos têm um limite de 20 grupos de consumidores por Hubs de Eventos. Quando você tenta criar mais, você recebe um QuotaExceededException.

TimeoutException

Uma TimeoutException indica que uma operação iniciada pelo utilizador está a demorar mais do que o tempo limite da operação.

Nos Hubs de Eventos, o tempo limite é especificado como parte da cadeia de ligação ou através do ServiceBusConnectionStringBuilder. A mensagem de erro em si pode variar, mas sempre contém o valor de tempo limite especificado para a operação atual.

Espera-se que os tempos limite ocorram durante ou entre as operações de manutenção, tais como as atualizações de serviço dos Hubs de Eventos (ou) atualizações de SO nos recursos que executam o serviço. Durante as atualizações de SO, as entidades são movidas e os nós são atualizados ou reiniciados, o que pode causar tempos limite. Para obter detalhes do contrato de nível de serviço (SLA) para o serviço Hubs de Eventos do Azure, consulte SLA para Hubs de Eventos.

Causas comuns

Há duas causas comuns para esse erro: configuração incorreta ou um erro de serviço transitório.

  • Configuração incorreta O tempo limite da operação pode ser muito pequeno para a condição operacional. O valor padrão para o tempo limite da operação no SDK do cliente é 60 segundos. Verifique se o seu código tem o valor definido como algo muito pequeno. A condição da rede e o uso da CPU podem afetar o tempo que leva para uma operação específica ser concluída, portanto, o tempo limite da operação não deve ser definido como um valor pequeno.
  • Erro de serviço transitório Às vezes, o serviço de Hubs de Eventos pode sofrer atrasos no processamento de solicitações, por exemplo, durante períodos de alto tráfego. Nesses casos, você pode tentar novamente a operação após um atraso, até que a operação seja bem-sucedida. Se a mesma operação ainda falhar após várias tentativas, visite o site de status do serviço do Azure para ver se há alguma interrupção de serviço conhecida.

ServerBusyException

Um Microsoft.ServiceBus.Messaging.ServerBusyException ou Microsoft.Azure.EventHubs.ServerBusyException indica que um servidor está sobrecarregado. Existem dois códigos de erro relevantes para esta exceção.

Código de erro 50002

Este erro pode ocorrer por um de dois motivos:

  • A carga não é distribuída uniformemente em todas as partições no hub de eventos e uma partição atinge a limitação da unidade de taxa de transferência local.

    Resolução: revisar a estratégia de distribuição de partições ou tentar EventHubClient.Send(eventDataWithOutPartitionKey) pode ajudar.

  • O namespace Hubs de Eventos não tem unidades de taxa de transferência suficientes (você pode verificar a tela Métricas na janela de namespace Hubs de Eventos no portal do Azure para confirmar). O portal mostra informações agregadas (1 minuto), mas medimos a taxa de transferência em tempo real – portanto, é apenas uma estimativa.

    Resolução: aumentar as unidades de taxa de transferência no namespace pode ajudar.

    Você pode configurar unidades de taxa de transferência na página Escala ou na página Visão geral da página de namespace Hubs de Eventos no portal do Azure. Ou, você pode usar Auto-inflate, que aumenta automaticamente aumentando o número de unidades de taxa de transferência, para atender às necessidades de uso.

    As unidades de taxa de transferência (TUs) aplicam-se a todos os hubs de eventos em um namespace de Hubs de Eventos. Isso significa que você compra TUs no nível de namespace e são compartilhados entre os hubs de eventos sob esse namespace. Cada TU dá direito ao namespace aos seguintes recursos:

    • Até 1 MB por segundo de eventos de entrada (eventos enviados para um hub de eventos), mas não mais de 1000 eventos de entrada, operações de gestão ou chamadas à API de controlo por segundo.
    • Até 2 MB por segundo de eventos de saída (eventos consumidos a partir de um hub de eventos), mas não mais de 4096 eventos de saída.
    • Até 84 GB de armazenamento de eventos (o suficiente para o período de retenção padrão de 1 hora).

    Na página Visão geral, na seção Mostrar métricas, alterne para a guia Taxa de transferência. Selecione o gráfico para abri-lo em uma janela maior com intervalos de 1 minuto no eixo x. Observe os valores de pico e divida-os por 60 para obter bytes de entrada/segundo ou bytes/segundo de saída. Use uma abordagem semelhante para calcular o número de solicitações por segundo nos horários de pico na guia Solicitações .

    Se você vir valores superiores ao número de limites de TUs * (1 MB por segundo para entrada ou 1000 solicitações de entrada/segundo, 2 MB por segundo para saída), aumente o número de TUs usando a página Escala (no menu à esquerda) de um namespace de Hubs de Eventos para aumentar manualmente ou usar o recurso de inflação automática de Hubs de Eventos. Você pode dimensionar até 40 TUs quando estiver dimensionando manualmente ou automaticamente o namespace.

Código de erro 50008

Este erro raramente deve ocorrer. Isso acontece quando o contêiner que executa o código para seu namespace está com pouca CPU – não mais do que alguns segundos antes do início do balanceador de carga dos Hubs de Eventos.

Resolução: limite chamadas para o método GetRuntimeInformation. Os Hubs de Eventos do Azure dão suporte a até 50 chamadas por segundo por grupo de consumidores para GetRuntimeInfo por segundo. Você pode receber uma exceção semelhante à seguinte quando o limite for atingido:

ExceptionId: 00000000000-00000-0000-a48a-9c908fbe84f6-ServerBusyException: The request was terminated because the namespace 75248:aaa-default-eventhub-ns-prodb2b is being throttled. Error code : 50008. Please wait 10 seconds and try again.

Próximos passos

Pode saber mais sobre os Hubs de Eventos ao aceder às seguintes ligações: