Compartilhar via

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

Este artigo lista as exceções do .NET geradas pelas 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, consulte o comunicado de desativação do suporte.

Categorias de exceções

As APIs de mensagens geram exceções que podem se enquadrar nas categorias a seguir, juntamente com a ação associada que você pode tomar 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: tente corrigir o código antes de prosseguir.
  2. Erro de configuração (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException, System.UnauthorizedAccessException. Ação geral: examine sua configuração e altere se necessário.
  3. Exceções transitórias (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Ação geral: repita a operação ou notifique os usuários. A RetryPolicy classe no SDK do cliente pode ser configurada para lidar com novas tentativas automaticamente. Para obter mais informações, consulte As 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 para o tipo de exceção; Consulte a tabela na seção a seguir:

Importante

  • O Barramento de Serviço do Azure não tenta novamente uma operação quando ocorre uma exceção na operação 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 lista os tipos de exceção de mensagens, suas causas e ações sugeridas que você pode tomar.

Tipo de exceção Descrição/causa/exemplos Ação sugerida Observação sobre repetição automática/imediata
Exceção de tempo limite O servidor não respondeu à operação solicitada dentro do tempo especificado, que é controlado pelo OperationTimeout. O servidor pode ter concluído a operação solicitada. Isso pode acontecer devido a atrasos na rede ou em outras infraestruturas. Verifique o estado do sistema quanto à consistência e tente novamente, se necessário. Consulte exceções de tempo limite. 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, Complete() 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 (Exceção de Acesso Não Autorizado) 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. 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 Create é 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. Verifique se a entidade existe. A repetição não ajuda.
MessageNotFoundException Tente 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 enviada para a fila de mensagens mortas. A repetição não ajuda.
Exceção de comunicação de mensagens O cliente não consegue estabelecer uma conexão com o Service Bus. Verifique se o nome do host fornecido está correto e se o host está acessível.

Se o código for executado em um ambiente com um firewall/proxy, verifique se o tráfego destinado ao domínio/endereço IP do Barramento de Serviço e às portas não está bloqueado.

 Tentar novamente poderá ajudar se houver problemas intermitentes de conectividade.
Exceção ServerBusyException O serviço não pode processar a solicitação neste momento. O cliente pode aguardar um período de tempo e tentar novamente a operação. O cliente pode tentar novamente após determinado intervalo. Se uma repetição resultar em uma exceção diferente, verifique o comportamento de repetição dessa exceção.
Exceção de mensagens A exceção de mensagens genéricas que pode ser gerada 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 de enviar uma mensagem maior que 256 KB.

O servidor ou serviço encontrou um erro durante o processamento da solicitação. Consulte a mensagem de exceção para obter detalhes. Geralmente é uma exceção transitória.

A solicitação foi encerrada porque a entidade está sendo limitada. Código de erro: 50001, 50002, 50008.

Verifique o código e verifique se apenas objetos serializáveis são usados para o corpo da mensagem (ou use um serializador personalizado).

Verifique a documentação dos tipos de valor com suporte das propriedades e use apenas tipos com suporte.

Verifique a propriedade IsTransient . Se for verdade, você poderá repetir a operação.

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.
Exceção de Entidade de Mensagens 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. A repetição não ajuda.
QuotaExceededException A entidade de mensagens atingiu seu 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. Consulte QuotaExceededException. Tentar novamente pode ajudar se as mensagens foram removidas nesse meio tempo.
Exceção de ação de regra O Barramento de Serviço retorna essa exceção se você tentar criar uma ação de regra inválida. O Barramento de Serviço anexa essa exceção a uma mensagem morta se ocorrer um erro durante o processamento da ação da regra dessa mensagem. Verifique se a ação da regra está correta. A repetição não ajuda.
Exceção de filtro O Service Bus retornará 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 essa mensagem. Verifique se o filtro está correto. A repetição não ajuda.
SessionCannotBeLockedException Tente aceitar uma sessão com uma ID de sessão específica, mas a sessão está bloqueada por outro cliente no momento. Verifique se a sessão está desbloqueada por outros clientes. Tentar novamente pode ajudar se a sessão tiver sido liberada nesse ínterim.
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.
Exceção de MensagemEntidadeDesabilitada Solicitação para uma operação de runtime em uma entidade desabilitada. Ative a entidade. A repetição poderá ajudar se a entidade tiver sido ativada nesse ínterim.
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 corresponde. 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.
Exceção de transação A transação 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 em dúvida ou é feita uma tentativa de confirmar a transação e a transação fica em dúvida. Seu aplicativo deve lidar com essa exceção (como um caso especial), pois a transação pode já ter sido confirmada. -

QuotaExceededException

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

Observação

Quanto às 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 está conseguindo concluir as mensagens e as mensagens são retornadas para a fila/tópico quando o bloqueio expira. Isso pode 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. O receptor parou. Um receptor parou de receber mensagens de uma fila ou assinatura. A maneira de identificá-lo é examinar a propriedade QueueDescription.MessageCountDetails , que mostra o detalhamento completo 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 o tempo limite ocorra durante ou entre operações de manutenção, como atualizações de serviço do Barramento de Serviço (ou) atualizações do sistema operacional em recursos que executam o serviço. Durante as atualizações do sistema operacional, as entidades são movidas e os nós são atualizados ou reinicializados, o que pode causar tempo limite. Para obter detalhes de Contrato de Nível de Serviço (SLA) para o serviço de Barramento de Serviço do Azure, consulte SLA para Barramento de Serviço.

Filas e tópicos

Quanto a filas e tópicos, o tempo limite é especificado na propriedade MessagingFactorySettings.OperationTimeout, como parte da cadeia de conexão ou pelo ServiceBusConnectionStringBuilder. A mensagem de erro em si pode variar, mas sempre contém o valor de tempo limite especificado para a operação atual.

MessageLockLostException

Motivo

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. Depois de reiniciado, o aplicativo cliente analisou as mensagens de bordo 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. Opcionalmente, o aplicativo cliente pode considerar o registro em log da exceção para análise, mas o cliente deve 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 chamar o recebimento.

Se o MaxDeliveryCount tiver excedido, a mensagem poderá ser movida para o DeadLetterQueue.

SessionLockLostException

Motivo

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 SessionLockLostException, ele não pode mais processar as mensagens na sessão. O aplicativo cliente pode considerar registrar em log a exceção para análise, mas o cliente deve 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.

Exceção de soquete

Motivo

Um SocketException é gerado 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.
  • Erro ao processar a mensagem ou o tempo limite é 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 consegue converter o nome <mynamespace>.servicebus.windows.net no 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 não for resolvido em um IP e o alias do 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.

Exceção de mensagens

Motivo

MessagingException é uma exceção genérica que pode ser gerada por vários motivos. Alguns dos motivos 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 fornecida. 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 de serviço e reinicializações.

Observação

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

Resolução

As etapas de resolução dependem do que causou o lançamento de MessagingException.

  • Para problemas transitórios (em que isTransient está definido como true) ou para problemas de limitação, tentar novamente a operação pode resolvê-la. A política de repetição padrão no SDK pode ser usada.
  • Para outros problemas, os detalhes na exceção indicam que as etapas de resolução do problema podem ser deduzidas dos mesmos.

StorageQuotaExceededException

Motivo

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

Resolução

  • Aumentar o número de unidades de mensagens atribuídas ao namespace premium
  • Se você já estiver usando unidades de mensagens máximas permitidas 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 obter dicas de solução de problemas, consulte o guia de solução de problemas.

  • Last updated on