Azure Relay exceptions

This article lists some exceptions that might be generated by the Azure Relay APIs. This reference is subject to change, so check back for updates.

Exception categories

The Relay APIs generate exceptions that might fall into the following categories. Also listed are suggested actions that you can take to help resolve the exceptions.

Exception types

The following table lists messaging exception types and their causes. It also notes suggested actions you can take to help resolve the exceptions.

Exception type Description Suggested action Note on automatic or immediate retry
Timeout The server did not respond to the requested operation within the specified time, which is controlled by OperationTimeout. The server might have completed the requested operation. This can happen due to network or other infrastructure delays. Check the system state for consistency, and then retry, if necessary. See TimeoutException. Retry might help in some cases; add retry logic to code.
Invalid Operation The requested user operation is not allowed within the server or service. See the exception message for details. Check the code and the documentation. Make sure that the requested operation is valid. Retry will not help.
Operation Canceled An attempt is made to invoke an operation on an object that has already been closed, aborted, or disposed. In rare cases, the ambient transaction is already disposed. Check the code and make sure it does not invoke operations on a disposed object. Retry will not help.
Unauthorized Access The TokenProvider object could not acquire a token, the token is invalid, or the token does not contain the claims required to perform the operation. Make sure that the token provider is created with the correct values. Check the configuration of the Access Control service. Retry might help in some cases; add retry logic to code.
Argument Exception,
Argument Null,
Argument Out Of Range
One or more of the following has occurred:
One or more arguments supplied to the method are invalid.
The URI supplied to NamespaceManager or Create contains one or more path segments.
The URI scheme supplied to NamespaceManager or Create is invalid.
The property value is larger than 32 KB.
Check the calling code and make sure the arguments are correct. Retry will not help.
Server Busy Service is not able to process the request at this time. The client can wait for a period of time, then retry the operation. The client might retry after a specific interval. If a retry results in a different exception, check the retry behavior of that exception.
Quota Exceeded The messaging entity has reached its maximum allowable size. Create space in the entity by receiving messages from the entity or its subqueues. See QuotaExceededException. Retry might help if messages have been removed in the meantime.
Message Size Exceeded A message payload exceeds the 256-KB limit. Note that the 256-KB limit is the total message size. The total message size can include system properties and any Microsoft .NET overhead. Reduce the size of the message payload, then retry the operation. Retry will not help.


QuotaExceededException indicates that a quota for a specific entity has been exceeded.

For Relay, this exception wraps the System.ServiceModel.QuotaExceededException, which indicates that the maximum number of listeners has been exceeded for this endpoint. This is indicated in the MaximumListenersPerEndpoint value of the exception message.


A TimeoutException indicates that a user-initiated operation is taking longer than the operation timeout.

Check the value of the ServicePointManager.DefaultConnectionLimit property. Reaching this limit also can cause a TimeoutException.

For Relay, you might receive timeout exceptions when you first open a relay sender connection. There are two common causes for this exception:

  • The OpenTimeout value might be too small (if even by a fraction of a second).
  • An on-premises relay listener might be unresponsive (or it might encounter firewall rules issues that prohibit listeners from accepting new client connections), and the OpenTimeout value is less than about 20 seconds.


'System.TimeoutException’: The operation did not complete within the allotted timeout of 00:00:10.
The time allotted to this operation may have been a portion of a longer timeout.

Common causes

There are two common causes for this error:

  • Incorrect configuration

    The operation timeout might be too small for the operational condition. The default value for the operation timeout in the client SDK is 60 seconds. Check to see whether the value in your code is set to something too small. Note that CPU usage and the condition of the network can affect the time it takes for an operation to complete. It's a good idea not to set the operation timeout to a very small value.

  • Transient service error

    Occasionally, the Relay service might experience delays in processing requests. This might happen, for example, during periods of high traffic. If this occurs, retry your operation after a delay, until the operation is successful. If the same operation continues to fail after multiple attempts, check the Azure service status site to see if there are known service outages.

Next steps