Excepciones de mensajería de Service Bus (en desuso)

En este artículo se enumeran las excepciones de .NET generadas por API de .NET Framework.

El 30 de septiembre de 2026, retiraremos del SDK de Azure Service Bus las bibliotecas WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus y com.microsoft.azure.servicebus, que no se ajusten a las directrices del SDK de Azure. También finalizaremos la compatibilidad con el protocolo SBMP, por lo que ya no podrá usar este protocolo después del 30 de septiembre de 2026. Migre a las bibliotecas más recientes del SDK de Azure, que ofrecen actualizaciones de seguridad críticas y funcionalidades mejoradas, antes de esa fecha.

Aunque las bibliotecas anteriores todavía se pueden usar después del 30 de septiembre de 2026, ya no recibirán soporte técnico oficial ni actualizaciones de Microsoft. Para obtener más información, consulte el anuncio de retirada de soporte técnico.

Categorías de excepciones

Las API de mensajería generan excepciones que pueden dividirse en las siguientes categorías, junto con la acción asociada que puede realizar para intentar corregirlas. El significado y las causas de una excepción pueden variar en función del tipo de entidad de mensajería:

  1. Error de codificación de usuario (System.ArgumentException, System.InvalidOperationException, System.OperationCanceledException, System.Runtime.Serialization.SerializationException). Acción general: intente corregir el código antes de continuar.
  2. Error de instalación/configuración (Microsoft.ServiceBus.Messaging.MessagingEntityNotFoundException y System.UnauthorizedAccessException). Acción general: revise la configuración y cámbiela si es necesario.
  3. Excepciones transitorias (Microsoft.ServiceBus.Messaging.MessagingException, Microsoft.ServiceBus.Messaging.ServerBusyException, Microsoft.ServiceBus.Messaging.MessagingCommunicationException). Acción general: intente realizar de nuevo la operación o informe a los usuarios. La clase RetryPolicy del SDK de cliente puede configurarse para controlar reintentos automáticamente. Consulte Instrucciones de reintento para más información.
  4. Otras excepciones (System.Transactions.TransactionException, System.TimeoutException, Microsoft.ServiceBus.Messaging.MessageLockLostException, Microsoft.ServiceBus.Messaging.SessionLockLostException). Acción general: específica del tipo de excepción; consulte la tabla de la siguiente sección:

Importante

  • Azure Service Bus no vuelve a intentar una operación en caso de excepción cuando la operación está en un ámbito de transacción.
  • Para obtener instrucciones de reintento específicas de Azure Service Bus, consulte Guía de reintento para Service Bus.

Tipos de excepciones

En la tabla siguiente se describen los tipos de excepción de mensajería, sus causas y las acciones sugeridas que puede realizar.

Tipo de excepción Descripción/causa/ejemplos Acción sugerida Nota sobre el reintento automático o inmediato
TimeoutException El servidor no respondió a la operación solicitada en el tiempo especificado, que está controlado por OperationTimeout. Puede que el servidor haya completado la operación solicitada. Esto puede producirse debido a un retraso de red o a otros retrasos de infraestructura. Compruebe la coherencia del estado del sistema y vuelva a intentarlo si es necesario. Consulte Excepciones de tiempo de espera. El reintento podría resultar útil en algunos casos; agregue lógica de reintento al código.
InvalidOperationException La operación del usuario solicitada no está permitida en el servidor o servicio. Consulte el mensaje de excepción para obtener detalles. Por ejemplo, Complete() genera esta excepción si el mensaje se recibió en el modo ReceiveAndDelete . Compruebe el código y la documentación. Asegúrese de que la operación solicitada sea válida. Los reintentos no funcionan.
OperationCanceledException Se realiza un intento para invocar una operación en un objeto que ya se ha cerrado, anulado o eliminado. En raras ocasiones, la transacción de ambiente ya se ha eliminado. Compruebe el código y asegúrese de que no invoca operaciones de un objeto desechado. Los reintentos no funcionan.
UnauthorizedAccessException El objeto TokenProvider no pudo adquirir un token, el token no es válido o no contiene las notificaciones necesarias para realizar la operación. Asegúrese de que el proveedor de tokens se cree con los valores correctos. Compruebe la configuración de Access Control Service. El reintento podría resultar útil en algunos casos; agregue lógica de reintento al código.
ArgumentException
ArgumentNullException
ArgumentOutOfRangeException
Uno o varios de los argumentos proporcionados para el método no son válidos.
El URI proporcionado a NamespaceManager o Create contiene segmentos de ruta de acceso.
El esquema de URI proporcionado a NamespaceManager o Create no es válido.
El valor de la propiedad es mayor de 32 KB.
Compruebe el código de llamada y asegúrese de que los argumentos sean correctos. Los reintentos no funcionan.
MessagingEntityNotFoundException La entidad asociada a la operación no existe o se eliminó. Asegúrese de que la entidad exista. Los reintentos no funcionan.
MessageNotFoundException Se intenta recibir un mensaje con una secuencia numérica concreta. Este mensaje no se encuentra. Asegúrese de que aún no se recibió el mensaje. Compruebe la cola de correo devuelto para ver si el mensaje se procesó como correo devuelto. Los reintentos no funcionan.
MessagingCommunicationException El cliente no puede establecer una conexión a Service Bus. Asegúrese de que el nombre de host proporcionado sea correcto y que este sea accesible.

Si el código se ejecuta en un entorno con un firewall o proxy, asegúrese de que el tráfico a la dirección IP o el dominio de Service Bus no esté bloqueado.

El reintento podría resultar útil si hay problemas de conectividad intermitente.
ServerBusyException El servicio no puede procesar la solicitud en este momento. El cliente puede esperar durante un período de tiempo y volver a intentar realizar la operación. El cliente puede volver a intentarlo tras un determinado intervalo de tiempo. Si el reintento genera otra excepción, compruebe el comportamiento de reintento de esa excepción.
MessagingException Excepción de mensajería genérica que puede producirse en los siguientes casos:

Se intentó crear QueueClient con un nombre o una ruta de acceso que pertenece a un tipo de entidad diferente (por ejemplo, un tema).

Intento de enviar un mensaje mayor de 256 KB.

El servidor o servicio encontró un error durante el procesamiento de la solicitud. Consulte el mensaje de excepción para obtener detalles. Por lo general, se trata de una excepción transitoria.

La solicitud finalizó porque la entidad se está limitando. Código de error: 50001, 50002, 50008.

Compruebe el código y asegúrese de que solo se usan objetos serializables en el cuerpo del mensaje (o use un serializador personalizado).

Consulte la documentación de los tipos de valor de las propiedades admitidos y use solo los tipos compatibles.

Compruebe la propiedad IsTransient . Si es true, puede volver a intentar la operación.

Si la excepción se debe a una limitación, espere unos segundos y vuelva a intentar la operación. El comportamiento de reintento es indefinido y quizá no resulte útil en otros escenarios.
MessagingEntityAlreadyExistsException Se intenta crear una entidad con un nombre que ya se usa en otra entidad de ese espacio de nombres de servicio. Elimine la entidad existente o elija un nombre diferente para la entidad que quiere crear. Los reintentos no funcionan.
QuotaExceededException La entidad de mensajería ha alcanzado su tamaño máximo permitido, o bien se superó el número máximo de conexiones en un espacio de nombres. Cree espacio en la entidad recibiendo mensajes de esta o de sus subcolas. Consulte QuotaExceededException. El reintento podría resultar útil si los mensajes se eliminan mientras este se lleva a cabo.
RuleActionException Service Bus devuelve esta excepción si se intenta crear una acción de regla no válida. Si se produjo un error al procesar la acción de regla de un mensaje, Service Bus adjunta esta excepción a dicho mensaje. Compruebe si la acción de regla es correcta. Los reintentos no funcionan.
FilterException Service Bus devuelve esta excepción si se intenta crear un filtro no válido. Si se produjo un error al procesar el filtro de un mensaje, Service Bus adjunta esta excepción a dicho mensaje. Compruebe si el filtro es correcto. Los reintentos no funcionan.
SessionCannotBeLockedException Se intenta aceptar una sesión con un id. de sesión específico, pero actualmente esta se encuentra bloqueada por otro cliente. Asegúrese de que otros clientes desbloqueen la sesión. El reintento podría ser útil si la sesión se publica mientras este se lleva a cabo.
TransactionSizeExceededException Hay demasiadas operaciones que forman parte de la transacción. Reduzca el número de operaciones que forman parte de esta transacción. Los reintentos no funcionan.
MessagingEntityDisabledException Solicitud para realizar una operación en tiempo de ejecución en una entidad deshabilitada. Active la entidad. El reintento podría ser útil si la entidad se activa mientras este se lleva a cabo.
NoMatchingSubscriptionException Service Bus devuelve esta excepción si envía un mensaje a un tema que tiene el filtrado previo habilitado y dicho mensaje no coincide con ninguno de los filtros. Asegúrese de que coincida con al menos un filtro. Los reintentos no funcionan.
MessageSizeExceededException Una carga de mensaje supera el límite de 256 KB. El límite de 256 KB es el tamaño total del mensaje, que puede incluir las propiedades del sistema y cualquier sobrecarga .NET. Reduzca el tamaño de la carga del mensaje y vuelva a intentar la operación. Los reintentos no funcionan.
TransactionException La transacción de ambiente (Transaction.Current) no es válida. Es posible que se haya completado o anulado. La excepción interna puede proporcionar información adicional. Los reintentos no funcionan.
TransactionInDoubtException Se intenta realizar una operación en una transacción dudosa o se intenta confirmar una transacción y esta se convierte en dudosa. La aplicación debe controlar esta excepción (como caso especial), porque puede que ya se haya confirmado la transacción. -

QuotaExceededException

QuotaExceededException indica que se ha superado una cuota de una entidad específica.

Nota

Para ver las cuotas de Service Bus, consulte Cuotas.

Colas y temas

Para las colas y los temas, suele tratarse del tamaño de la cola. La propiedad de mensaje de error contiene más detalles, como en el ejemplo siguiente:

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

El mensaje indica que el tema superaba su límite de tamaño, en este caso 1 GB (el límite de tamaño predeterminado).

Espacios de nombres

Para espacios de nombres, QuotaExceededException puede indicar que una aplicación ha superado el número máximo de conexiones en un espacio de nombres. Por ejemplo:

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

Causas comunes

Hay dos causas comunes de este error: la cola de mensajes fallidos y receptores de mensajes que no funcionan.

  1. Cola de mensajes fallidos Un lector no puede completar los mensajes, que se devuelven a la cola o tema al expirar el bloqueo. Esto puede suceder si el lector encuentra una excepción que impide que llame a BrokeredMessage.Complete. Una vez que un mensaje se ha leído 10 veces, se mueve a la cola de mensajes fallidos de forma predeterminada. La propiedad QueueDescription.MaxDeliveryCount controla este comportamiento, que tiene un valor predeterminado de 10. Al acumularse los mensajes en la cola de mensajes fallidos, estos ocupan espacio.

    Para resolver el problema, lea y complete los mensajes de la cola de mensajes fallidos, igual que haría si se encontraran en cualquier otra cola. Puede usar el método FormatDeadLetterPath para ayudar a dar formato a la ruta de acceso de la cola de mensajes fallidos.

  2. Receptor detenido. Un receptor ha dejado de recibir mensajes de una cola o suscripción. Para identificar este aspecto, eche un vistazo a la propiedad QueueDescription.MessageCountDetails , que muestra el desglose completo de los mensajes. Si la propiedad ActiveMessageCount es alta o creciente, los mensajes no se leen tan rápido como se escriben.

TimeoutException

TimeoutException indica que la operación iniciada por el usuario está superando el tiempo de espera.

Debe comprobar el valor de la propiedad ServicePointManager.DefaultConnectionLimit, porque si alcanza este límite también puede causar una excepción TimeoutException.

Se espera que se produzcan tiempos de espera durante o entre operaciones de mantenimiento, como por ejemplo durante las actualizaciones del servicio Service Bus (o) actualizaciones del sistema operativo en los recursos que ejecutan el servicio. Durante las actualizaciones del sistema operativo, las entidades se mueven alrededor de los nodos y se actualizan o se reinician, lo que puede provocar tiempos de espera. Para obtener detalles sobre el contrato de nivel de servicio (SLA) para el servicio Azure Service Bus, consulte SLA para Service Bus.

Colas y temas

Para las colas y los temas, el tiempo de espera se especifica en la propiedad MessagingFactorySettings.OperationTimeout como parte de la cadena de conexión o mediante ServiceBusConnectionStringBuilder. El propio mensaje de error puede variar, pero siempre contiene el valor de tiempo de espera especificado para la operación actual.

MessageLockLostException

Causa

MessageLockLostException se produce cuando se recibe un mensaje mediante el modo Receive PeekLock y el bloqueo mantenido por el cliente expira en el lado del servicio.

El bloqueo de un mensaje puede expirar debido a varios motivos:

  • El temporizador de bloqueo ha expirado antes de que la aplicación cliente lo renovara.
  • La aplicación cliente adquirió el bloqueo, lo guardó en un almacén persistente y luego se reinició. Una vez que se reinició, la aplicación cliente examinó los mensajes en proceso e intentó completarlos.

También puede recibir esta excepción en los escenarios siguientes:

  • Actualización del servicio
  • Actualización del sistema operativo
  • Al cambiar las propiedades de la entidad (cola, tema, suscripción) mientras se mantiene el bloqueo.

Solución

Cuando una aplicación cliente recibe MessageLockLostException, ya no puede procesar el mensaje. De manera opcional, la aplicación cliente puede considerar registrar la excepción para su análisis, pero el cliente debe eliminar el mensaje.

Dado que el bloqueo del mensaje ha expirado, volvería a la cola (o suscripción), y la siguiente aplicación cliente que llame a Receive podría procesarlo.

Si se ha superado MaxDeliveryCount, es posible que el mensaje se mueva a DeadLetterQueue.

SessionLockLostException

Causa

SessionLockLostException se produce cuando se acepta una sesión y el bloqueo mantenido por el cliente expira en el lado del servicio.

El bloqueo de una sesión puede expirar debido a varios motivos:

  • El temporizador de bloqueo ha expirado antes de que la aplicación cliente lo renovara.
  • La aplicación cliente adquirió el bloqueo, lo guardó en un almacén persistente y luego se reinició. Una vez que se reinició, la aplicación cliente examinó las sesiones en proceso e intentó procesar los mensajes de esas sesiones.

También puede recibir esta excepción en los escenarios siguientes:

  • Actualización del servicio
  • Actualización del sistema operativo
  • Al cambiar las propiedades de la entidad (cola, tema, suscripción) mientras se mantiene el bloqueo.

Solución

Cuando una aplicación cliente recibe SessionLockLostException, ya no puede procesar los mensajes en la sesión. La aplicación cliente puede considerar registrar la excepción para su análisis, pero el cliente debe eliminar el mensaje.

Dado que el bloqueo de la sesión ha expirado, volvería a la cola (o suscripción), y la siguiente aplicación cliente que acepte la sesión podría bloquearla. Dado que una única aplicación cliente mantiene el bloqueo de la sesión en un momento dado, el procesamiento en orden está garantizado.

SocketException

Causa

SocketException se produce en los casos siguientes:

  • Cuando se produce un error en un intento de conexión porque el host no respondió correctamente después de un tiempo especificado (código de error de TCP 10060).
  • Hubo un error en una conexión establecida porque el host conectado no respondió.
  • Hubo un error al procesar el mensaje o el host remoto superó el tiempo de espera.
  • Problema de recursos de red subyacentes.

Solución

Los errores SocketException indican que la VM que hospeda las aplicaciones no puede convertir el nombre <mynamespace>.servicebus.windows.net en la dirección IP correspondiente.

Compruebe si el comando siguiente logra una asignación a una dirección IP.

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

Lo que proporcionaría una salida como la siguiente:

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

Si el nombre anterior no se resuelve en una dirección IP y en el alias del espacio de nombres, pida al administrador de red que investigue. La resolución de nombres se realiza a través de un servidor DNS, normalmente un recurso de la red del cliente. Si la resolución de DNS se realiza mediante Azure DNS, póngase en contacto con Soporte técnico de Azure.

Si la resolución de nombres funciona según lo previsto, compruebe aquí si se permite la conexión a Azure Service Bus.

MessagingException

Causa

MessagingException es una excepción genérica que puede producirse por varios motivos. Algunas de las razones son:

  • Se realiza un intento de crear una clase QueueClient en un Tema o una Suscripción.
  • El tamaño del mensaje enviado es mayor que el límite para el nivel dado. Lea más sobre los límites y cuotas de Service Bus.
  • Se finalizó la solicitud del plano de datos específica (envío, recepción, finalización, abandono) debido a la limitación.
  • Problemas transitorios causados por actualizaciones y reinicios del servicio.

Nota

La lista anterior de excepciones no es exhaustiva.

Solución

Los pasos de resolución dependen de lo que haya provocado el error MessagingException.

  • Para problemas transitorios (donde isTransient está establecido en true) o para problemas de limitación, volver a intentar la operación puede ser una solución. Para esto, puede aprovecharse la directiva de reintentos predeterminada en el SDK.
  • Por otros problemas, los detalles de la excepción indican el problema, y los pasos de resolución se pueden deducir desde allí.

StorageQuotaExceededException

Causa

La excepción StorageQuotaExceededException se genera cuando el tamaño total de las entidades de un espacio de nombres prémium supera el límite de 1 TB por unidad de mensajería.

Resolución

  • Aumentar el número de unidades de mensajería asignadas al espacio de nombres prémium.
  • Si ya usa el número máximo de unidades de mensajería permitidas para un espacio de nombres, cree un espacio de nombres independiente.

Pasos siguientes

Para obtener la referencia completa de la API de .NET para Service Bus, consulte la referencia de la API de .NET de Azure. Para obtener consejos de solución de problemas, consulte la Guía de solución de problemas.