Exceções de mensagens do Barramento de Serviço (preterido)

Este artigo lista as exceções do .NET geradas por APIs do .NET Framework.

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 poderão 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 de mensagens geram exceções que podem se enquadrar nas categorias a seguir, junto com a ação associada que pode ser tomada para tentar corrigi-las. O significado e as causas de uma exceção podem variar dependendo do tipo de entidade de mensagens:

1. Erro de codificação do usuário (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). Ação geral: tentar corrigir o código antes de prosseguir.
2. Erro de instalação/configuração (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. Ação geral: examinar sua configuração e alterá-la, se necessário.
3. Exceções temporárias (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Ação geral: repetir a operação ou notificar os usuários. A classe RetryPolicy no SDK do cliente pode ser configurada para lidar com novas tentativas automaticamente. Para obter mais informações, confira Diretrizes de repetição.
4. Outras exceções (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). Ação geral: específica ao tipo de exceção; consulte a tabela na seguinte seção:

Importante

• O Barramento de Serviço do Azure não repetirá uma operação no caso de uma exceção quando a operação estiver em um escopo de transação.
• Para obter diretrizes de repetição específicas para o Barramento de Serviço do Azure, consulte Diretrizes de repetição para o Barramento de Serviço.

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. Isso 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. Confira 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.	A repetição não ajuda.
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.	A repetição não ajuda.
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 segmentos 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.	A repetição não ajuda.
MessagingEntityNotFoundException	A entidade associada à operação não existe ou foi excluída.	Certifique-se de que a entidade existe.	A repetição não ajuda.
MessageNotFoundException	Tentativa para receber uma mensagem com um número de sequência específico. Esta mensagem não foi encontrada.	Verifique se a mensagem ainda não foi recebida. Verifique a fila de mensagens mortas para ver se a mensagem foi colocada ali.	A repetição não ajuda.
MessagingCommunicationException	O cliente não pode estabelecer uma conexão com o Barramento de Serviço.	Verifique se o nome de host fornecido está correto e se o host está acessível. Se o seu código for executado em um ambiente com um firewall/proxy, verifique se o tráfego para o endereço IP/domínio e as portas do Barramento de Serviço não está bloqueado.	Tentar novamente poderá ajudar se houver problemas intermitentes de conectividade.
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.	O cliente pode repetir a operação 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 que pode ser gerada 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 de TAn é feita para enviar uma mensagem maior que 256 KB. O servidor ou o serviço encontrou um erro durante o processamento da solicitação. Consulte a mensagem de exceção para obter detalhes. Isso geralmente é uma exceção temporária. A solicitação foi encerrada porque a entidade está sendo limitada. Código de erro: 50001, 50002, 50008.	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 ela for true, você poderá tentar a operação novamente.	Se a exceção for devido à limitação, aguarde alguns segundos e repita a operação. O comportamento de repetição é indefinido e pode não ajudar em outros cenários.
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.	A repetição não ajuda.
QuotaExceededException	A entidade de mensagens atingiu o tamanho máximo permitido ou o número máximo de conexões com um namespace foi excedido.	Crie espaço na entidade ao receber mensagens da entidade ou de suas subfilas. Confira QuotaExceededException.	Tentar novamente pode ajudar se as mensagens foram removidas nesse meio tempo.
RuleActionException	O Barramento de Serviço retorna essa exceção se você tentar criar uma ação de regra inválida. Barramento de Serviço anexa essa exceção a uma mensagem morta se ocorrer um erro ao processar a ação de regra para a mensagem.	Verifique se a ação da regra está correta.	A repetição não ajuda.
FilterException	O Barramento de Serviço retorna essa exceção se você tentar criar um filtro inválido. O Barramento de Serviço anexa essa exceção a uma mensagem morta se ocorreu um erro ao processar o filtro para a mensagem.	Verifique se o filtro está correto.	A repetição não ajuda.
SessionCannotBeLockedException	Tentativa de aceitar uma sessão com uma ID de sessão específica, mas a sessão está atualmente bloqueada por outro cliente.	Verifique se a sessão foi desbloqueada por outros clientes.	Tentar novamente pode ajudar se a sessão foi liberada nesse meio tempo.
TransactionSizeExceededException	Muitas operações fazem parte da transação.	Reduza o número de operações que fazem parte dessa transação.	A repetição não ajuda.
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.
NoMatchingSubscriptionException	O Barramento de Serviço retornará essa exceção se você enviar uma mensagem para um tópico que tenha a pré-filtragem habilitada e se nenhum dos filtros for correspondente.	Verifique se pelo menos um filtro é compatível.	A repetição não ajuda.
MessageSizeExceededException	O conteúdo de uma mensagem excede o limite de 256 KB. O limite de 256 KB é o tamanho total da mensagem, que pode incluir propriedades do sistema e qualquer sobrecarga do .NET.	Reduza o tamanho da carga de mensagem e repita a operação.	A repetição não ajuda.
TransactionException	A transação de ambiente (Transaction.Current) é inválida. Ela pode ter sido concluída ou anulada. A exceção interna pode fornecer informações adicionais.		A repetição não ajuda.
TransactionInDoubtException	Uma operação é tentada em uma transação incerta, ou uma tentativa é feita para confirmar a transação e ela se torna incerta.	Seu aplicativo precisa tratar essa exceção (como um caso especial), visto que a transação pode já ter sido confirmada.	-

QuotaExceededException

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

Observação

Para cotas do Barramento de Serviço, consulte Cotas.

Filas e tópicos

Para filas e tópicos, isso geralmente é o tamanho da fila. A propriedade de mensagem de erro contém mais detalhes, como no exemplo a seguir:

Microsoft.ServiceBus.Messaging.QuotaExceededException
Message: The maximum entity size has been reached or exceeded for Topic: 'xxx-xxx-xxx'. 
    Size of entity in bytes:1073742326, Max entity size in bytes:
1073741824..TrackingId:xxxxxxxxxxxxxxxxxxxxxxxxxx, TimeStamp:3/15/2013 7:50:18 AM

A mensagem informa que o tópico excedeu seu limite de tamanho, neste caso 1 GB (o limite de tamanho padrão).

Namespaces

Para namespaces, QuotaExceededException pode indicar que um aplicativo excedeu o número máximo de conexões com um namespace. Por exemplo:

Microsoft.ServiceBus.Messaging.QuotaExceededException: ConnectionsQuotaExceeded for namespace xxx.
<tracking-id-guid>_G12 ---> 
System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: 
ConnectionsQuotaExceeded for namespace xxx.

Causas comuns

Há duas causas comuns desse erro: a fila de mensagens mortas e os destinatários de mensagem não estão funcionando.

1. Fila de mensagens mortas Um leitor não pode concluir as mensagens e as mensagens são retornadas para fila/tópico quando o bloqueio expira. Isso poderá acontecer se o leitor encontrar uma exceção que o impeça de chamar BrokeredMessage.Complete. Depois que uma mensagem foi lida 10 vezes, ela é movida para a fila de mensagens mortas por padrão. Esse comportamento é controlado pela propriedade QueueDescription.MaxDeliveryCount e tem um valor padrão de 10. Conforme as mensagens são acumuladas na fila de mensagens mortas, elas ocupam espaço.

   Para resolver o problema, leia e conclua as mensagens da fila de mensagens mortas, como faria em qualquer outra fila. Você pode usar o método FormatDeadLetterPath para ajudar a formatar o caminho da fila de mensagens mortas.

2. Receptor parado. Um receptor parou de receber mensagens de uma fila ou assinatura. A maneira de identificar isso é examinar a propriedade QueueDescription.MessageCountDetails , que mostra a análise completa das mensagens. Se a propriedade ActiveMessageCount for alta ou em expansão, as mensagens não serão lidas tão rapidamente quanto são escritas.

TimeoutException

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

Você deve verificar o valor da propriedade ServicePointManager.DefaultConnectionLimit, pois atingir esse limite também pode causar um TimeoutException.

Espera-se que os tempos limite ocorram durante ou entre operações de manutenção, como atualizações de serviço do Barramento de Serviço (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 Barramento de Serviço do Azure, confira SLA para Barramento de Serviço.

Filas e tópicos

Para filas e tópicos, o tempo limite é especificado na propriedade MessagingFactorySettings.OperationTimeout, 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.

MessageLockLostException

Causa

A MessageLockLostException é gerada quando uma mensagem é recebida usando o modo de recebimento PeekLock e o bloqueio mantido pelo cliente expira no lado do serviço.

O bloqueio em uma mensagem pode expirar devido a vários motivos:

• O temporizador de bloqueio expirou antes de ser renovado pelo aplicativo cliente.
• O aplicativo cliente adquiriu o bloqueio, salvou-o em um repositório persistente e, em seguida, reiniciou. Após a reinicialização, o aplicativo cliente examinou as mensagens em andamento e tentou concluí-las.

Você também pode receber essa exceção nos seguintes cenários:

• Atualização de serviço
• Atualização do SO
• Alterando propriedades na entidade (fila, tópico, assinatura) enquanto mantém o bloqueio.

Resolução

Quando um aplicativo cliente recebe MessageLockLostException, ele não pode mais processar a mensagem. O aplicativo cliente pode, opcionalmente, considerar o registro em log da exceção para análise, mas o cliente precisa descartar a mensagem.

Como o bloqueio na mensagem expirou, ela volta para a fila (ou assinatura) e pode ser processada pelo próximo aplicativo cliente que chama o recebimento.

Se a MaxDeliveryCount for excedida, a mensagem poderá ser movida para a DeadLetterQueue.

SessionLockLostException

Causa

O SessionLockLostException é gerado quando uma sessão é aceita e o bloqueio mantido pelo cliente expira no lado do serviço.

O bloqueio em uma sessão pode expirar devido a vários motivos:

• O temporizador de bloqueio expirou antes de ser renovado pelo aplicativo cliente.
• O aplicativo cliente adquiriu o bloqueio, salvou-o em um repositório persistente e, em seguida, reiniciou. Depois de reiniciado, o aplicativo cliente examinou as sessões em andamento e tentou processar as mensagens nessas sessões.

Você também pode receber essa exceção nos seguintes cenários:

• Atualização de serviço
• Atualização do SO
• Alterando propriedades na entidade (fila, tópico, assinatura) enquanto mantém o bloqueio.

Resolução

Quando um aplicativo cliente recebe uma SessionLockLostException, ele não pode mais processar as mensagens na sessão. O aplicativo cliente pode considerar o registro em log da exceção para análise, mas o cliente precisa descartar a mensagem.

Como o bloqueio na mensagem expirou, ela volta para a fila (ou assinatura) e pode ser bloqueada pelo próximo aplicativo cliente que aceita a sessão. Como o bloqueio de sessão é mantido por um único aplicativo cliente em um determinado momento, o processamento em ordem é garantido.

SocketException

Causa

Uma SocketException é lançada nos seguintes casos:

• Em caso de falha de uma tentativa de conexão porque o host não respondeu corretamente após uma hora especificada (código de erro TCP 10060).
• Uma conexão estabelecida falhou porque o host conectado falhou ao responder.
• Ocorreu um erro ao processar a mensagem ou o tempo limite foi excedido pelo host remoto.
• Problema de recurso de rede subjacente.

Resolução

Os erros SocketException indicam que a VM que hospeda os aplicativos não pode converter o nome <mynamespace>.servicebus.windows.net para o endereço IP correspondente.

Verifique se o comando a seguir tem êxito no mapeamento para um endereço IP.

PS C:\> nslookup <mynamespace>.servicebus.windows.net

Que deve fornecer uma saída como:

Name:    <cloudappinstance>.cloudapp.net
Address:  XX.XX.XXX.240
Aliases:  <mynamespace>.servicebus.windows.net

Se o nome acima não for resolvido para um IP e o alias de namespace, entre em contato com o administrador da rede para uma investigação mais detalhada. A resolução de nomes é feita por meio de um servidor DNS que normalmente é um recurso na rede do cliente. Se a resolução de DNS for feita pelo DNS do Azure, entre em contato com o Suporte do Azure.

Se a resolução de nomes funcionar conforme o esperado, verifique aqui se as conexões com o Barramento de Serviço do Azure são permitidas.

MessagingException

Causa

MessagingException é uma exceção genérica que pode ser gerada por vários motivos. Algumas das razões são:

• É feita uma tentativa de criar um QueueClient em um tópico ou uma assinatura.
• O tamanho da mensagem enviada é maior que o limite para a camada especificada. Leia mais sobre as cotas e limitesdo Barramento de Serviço.
• A solicitação do plano de dados específico (enviar, receber, concluir, abandonar) foi encerrada devido à limitação.
• Problemas transitórios causados devido a atualizações e reinicializações de serviço.

Observação

A lista de exceções acima não é exaustiva.

Resolução

As etapas de resolução dependem do motivo pelo qual MessagingException foi gerada.

• A repetição da operação talvez resolva problemas transitórios (em que isTransient é definido como true) ou problemas de limitação. A política de repetição padrão no SDK pode ser usada para isso.
• Detalhes de outros problemas podem ser obtidos nos detalhes na exceção, permitindo a dedução das respectivas etapas de resolução.

StorageQuotaExceededException

Causa

O StorageQuotaExceededException é gerado quando o tamanho total de entidades em um namespace Premium excede o limite de 1 TB por unidade do sistema de mensagens.

Resolução

• Aumentar o número de unidades do sistema de mensagens atribuídas ao namespace Premium
• Se você já estiver usando o número máximo de unidades do sistema de mensagens permitido para um namespace, crie um namespace separado.

Próximas etapas

Para obter a referência completa da API do .NET de Barramento de Serviço, consulte a Referência de API do .NET do Azure. Para ver dicas de solução de problemas, confira o Guia de solução de problemas.