Client Throttling

How does it work

MSAL detects certain conditions (see below) where the application should not make repeated calls to AAD. If a call is made, then an MsalThrottledServiceException or an MsalThrottledUiRequiredException is thrown by MSAL. These are subtypes of MsalServiceException, so this behaviour does not introduce a breaking change. If MSAL would not apply client-side throttling, the application would still not be able to acquire tokens, as AAD would throw the error.

Recommended Pattern

The following coding pattern is recommended for obtaining the token.

            try
            {
                // acquire token silent
            IEnumerable<IAccount> accounts = await _pca.GetAccountsAsync();
            authResult = await _pca.AcquireTokenSilent(...)   
               .ExecuteAsync().ConfigureAwait(false);
            }
            catch (MsalUiRequiredException)
            {
                // acquire token interactive
            authResult = await _pca.AcquireTokenInteractive(...)
                .ExecuteAsync().ConfigureAwait(false);

            }

Conditions to get throttled

AAD is telling the application to back off

If the server is having problems or if an application is requesting tokens too often, AAD will respond with HTTP 429 (Too Many Requests) and with Retry-After header, Retry-After X seconds. The application will see an MsalServiceException with header details. The throttling state is maintained for the X seconds. Affects all flows. Introduced in 4.13.0.

AAD is having problems

If AAD is having problems it may respond with an HTTP 5xx error code with no Retry-After header. The throttling state is maintained for 1 minute. Affects only public client flows. Introduced in 4.13.0

Application is ignoring MsalUiRequiredException

MSAL throws MsalUiRequiredException when authentication cannot be resolved silently and the end-user needs to use a browser. This is a common occurrence when a tenant admin introduced 2FA or when a user password expires. Retrying the silent authentication cannot succeed. The throttling state is maintained for 2 minutes. Affects only the AcquireTokenSilent. Introduced in 4.14.0

Different cache being used for the same account

If you are using multiple cache for the same account, it can cause multiple requests to the backend and may cause throttling.

Force Refresh

If you are using WithForceRefresh(true), it will ignore the cache and make calls to the backend. This may result in too many calls causing it to throttle.