Exceções de mensagens dos Hubs de Eventos – .NET (herdados)

  • Artigo

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

Importante

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

Para obter informações sobre o EventHubsException gerado pela nova biblioteca .NET, confira 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, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

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, confira o anúncio de desativação do suporte.

Categorias de exceções

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

Tipos de exceção

A tabela a seguir relaciona os tipos de mensagens de exceção e suas causas e aponta a ação sugerida que você pode tomar.

Tipo de exceção Descrição/Causa/Exemplos Ação sugerida Observação sobre 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. Essa exceção pode acontecer devido a atrasos de rede ou outros atrasos de infraestrutura. Verifique o estado do sistema para manter a consistência e tente novamente, se necessário.
Veja TimeoutException.		 Uma nova tentativa pode ajudar em alguns casos; Adicione lógica de repetição ao código.
InvalidOperationException A operação solicitada pelo usuário não é permitida no servidor ou serviço. Consulte a mensagem de exceção para obter detalhes. Por exemplo, Concluir gerará essa exceção se a mensagem tiver sido recebida no modo ReceiveAndDelete . Verifique o código e a documentação. Verifique se a operação solicitada é válida. Tentar novamente não ajudará.
OperationCanceledException É feita uma tentativa de invocar uma operação em um objeto que já foi fechado, anulado ou descartado. Em casos raros, a transação de ambiente já foi descartada. Confira o código e verifique se ele não invoca operações em um objeto descartado. Tentar novamente não ajudará.
UnauthorizedAccessException O objeto TokenProvider não pôde adquirir um token, o token é inválido ou não contém as declarações necessárias para executar a operação. Verifique se o provedor de token for criado com os valores corretos. Verifique a configuração do Serviço de Controle de Acesso. Uma nova tentativa pode ajudar em alguns casos; Adicione lógica de repetição ao código.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException		 Um ou mais argumentos fornecidos para o 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 Criar é inválido. O valor da propriedade é maior do que 32 KB. Verifique o código de chamada e certifique-se de que os argumentos estão corretos. Tentar novamente 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. Tentar novamente não ajudará.
MessagingCommunicationException O cliente não pode estabelecer uma conexão com os Hubs de Eventos. Verifique se o nome de host fornecido está correto e se o host está acessível. Tentar novamente poderá ajudar se houver problemas intermitentes de conectividade.
Microsoft.ServiceBus.Messaging ServerBusyException

Microsoft.Azure.EventHubs ServerBusyException		 O serviço não pode processar a solicitação neste momento. O cliente pode esperar um período de tempo e repetir a operação.
Veja ServerBusyException.		 O cliente pode tentar novamente após um intervalo determinado. Se uma nova tentativa resultar em uma exceção diferente, verifique o comportamento de repetição de tal exceção.
MessagingException A exceção de mensagens genéricas pode ser lançada nos seguintes casos: uma tentativa é feita para criar um QueueClient usando um nome ou caminho que pertence a um tipo de entidade diferente (por exemplo, um tópico). A tentativa é feita para enviar uma mensagem maior que 1 MB. O servidor ou o serviço encontrou um erro durante o processamento da solicitação. Consulte a mensagem de exceção para obter detalhes. Essa exceção geralmente é uma exceção transitória. Verifique o código e certifique-se de que somente objetos serializáveis sejam usados para o corpo da mensagem (ou use um serializador personalizado). Verifique a documentação para os tipos de valor com suporte das propriedades e somente os tipos de uso com suporte. Verifique a propriedade IsTransient . Se for true, você pode tentar a operação novamente. O comportamento de repetição é indefinido e pode não ajudar.
MessagingEntityAlreadyExistsException Tentativa de criar uma entidade com um nome que já está sendo usado por outra entidade no namespace de serviço. Exclua a entidade existente ou escolha um nome diferente para a entidade a ser criada. Tentar novamente não ajudará.
QuotaExceededException A entidade de mensagens atingiu seu tamanho máximo permitido. Essa exceção pode acontecer se o número máximo de receptores (que é 5) já tiver sido aberto em um nível de grupo por consumidor. Crie espaço na entidade ao receber mensagens da entidade ou de suas subfilas.
See QuotaExceededException		 Tentar novamente pode ajudar se as mensagens foram removidas nesse meio tempo.
MessagingEntityDisabledException Solicitação para uma operação de runtime em uma entidade desabilitada. Ativar a entidade. Tentar novamente poderá ajudar se a entidade tiver sido ativada durante o processo.
Microsoft.ServiceBus.Messaging MessageSizeExceededException

Microsoft.Azure.EventHubs MessageSizeExceededException		 Um conteúdo 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 de mensagem e repita a operação. Tentar novamente não ajudará.

QuotaExceededException

QuotaExceededException indica que uma cota para uma entidade específica foi excedida.

Essa exceção pode acontecer se o número máximo de receptores (5) já tiver sido aberto em um nível de grupo por consumidor.

Hubs de Eventos

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

TimeoutException

Um TimeoutException indica que uma operação iniciada pelo usuário está demorando mais do que o tempo limite da operação.

Para os Hubs de Eventos, o tempo limite é especificado como parte da cadeia de conexão ou por meio de ServiceBusConnectionStringBuilder. A mensagem de erro pode variar, mas ele sempre contém o valor de tempo limite especificado para a operação atual.

Espera-se que os tempos limite ocorram durante ou entre operações de manutenção, como atualizações de serviço dos Hubs de Eventos (ou) atualizações de sistema operacional em recursos que executam o serviço. Durante as atualizações de sistema operacional, as entidades são movidas e os nós são atualizados ou reinicializados, o que pode fazê-los atingir o tempo limite. Para obter detalhes de SLA (Contrato de Nível de Serviço) para o serviço de Hubs de Eventos do Azure, confira SLA para Hubs de Eventos.

Causas comuns

Há duas causas comuns desse 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 é de 60 segundos. Verifique para ver se o código tem o valor definido para algo muito pequeno. A condição da rede e do uso da CPU pode afetar o tempo necessário para uma determinada operação ser concluída, portanto o tempo limite da operação não deve ser definido com um valor pequeno.
  • Erro de serviço temporário Às vezes, o serviço de Hubs de Eventos pode sofrer atrasos nas solicitações de processamento; por exemplo, durante os períodos de tráfego intenso. Nesses casos, você pode repetir a operação após um atraso, até que a operação seja bem-sucedida. Se a mesma operação continuar falhando após várias tentativas, visite o site de status do serviço do Azure para ver se há qualquer interrupção de serviço conhecida.

ServerBusyException

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

Código do erro 50002

Esse erro pode ocorrer por um dos seguintes motivos:

  • A carga não é distribuída igualmente entre todas as partições no Hub de Eventos e uma partição atinge a limitação de unidade de produtividade local.

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

  • O namespace dos Hubs de Eventos não tem unidades de produtividade suficientes (você pode conferir a tela Métricas na janela Namespace de 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 produtividade no namespace pode ajudar.

    Você pode configurar unidades de produtividade na página Escala ou na página Visão geral da página Namespace dos Hubs de Eventos no portal do Azure. Ou você pode usar a Ampliação automática, que é escalada verticalmente de maneira automática aumentando o número de unidades de produtividade, para atender às necessidades de uso.

    As TUs (unidades de produtividade) se aplicam a todos os hubs de eventos em um namespace dos Hubs de Eventos. Isso significa que você compra TUs no nível do namespace e elas são compartilhadas entre os hubs de eventos no namespace. Cada TU proporciona ao namespace os seguintes recursos:

    • Até 1 MB por segundo de eventos de entrada (eventos enviados para um Hub de Eventos), mas não mais de 1.000 eventos de entrada, operações de gerenciamento ou chamadas por segundo à API de controle.
    • Até 2 MB por segundo de eventos de saída (eventos consumidos de um Hub de Eventos), mas não mais do que 4096 eventos de saída.
    • Até 84 GB de armazenamento de eventos (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, mude para a guia Taxa de transferência. Selecione o gráfico para abri-lo em uma janela maior com intervalos de um minuto no eixo x. Examine os valores de pico e divida-os por 60 para obter bytes de entrada/segundo ou bytes de saída/segundo. Use uma abordagem semelhante para calcular o número de solicitações por segundo em horários de pico na guia Solicitações.

    Se você vir valores maiores do que o número de limites de TUs * limites (1 MB por segundo para entrada ou mil solicitações para entrada/segundo, 2 MB por segundo para saída), aumente o número de TUs usando a página Escala (no menu esquerdo) de um namespace dos Hubs de Eventos para dimensionar mais manualmente ou usar o recurso Ampliação automática dos Hubs de Eventos. Você pode escalar verticalmente até 40 TUs quando estiver dimensionando o namespace manualmente ou automaticamente.

Código de erro 50008

Esse erro deve ocorrer raramente. Isso acontece quando o contêiner executando o código para seu namespace é insuficiente na CPU – não mais do que alguns segundos, antes de o balanceador de carga dos Hubs de Eventos ser iniciado.

Resolução: limite as chamadas ao método GetRuntimeInformation. Os Hubs de Eventos do Azure dão suporte a até 50 chamadas por segundo por grupo de consumidores para o GetRuntimeInfo por segundo. Você poderá receber uma exceção semelhante à seguinte uma vez que 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óximas etapas

Você pode saber mais sobre Hubs de Eventos visitando os links abaixo: