learn.microsoft.com

Handle errors and exceptions in MSAL.NET - Microsoft Authentication Library for .NET

4/6/2024Updated 3/28/2025

Excerpt

## Conditional Access and claims challenges When getting tokens silently, your application may receive errors when a Conditional Access claims challenge such as MFA policy is required by an API you're trying to access. The pattern for handling this error is to interactively acquire a token using MSAL. This prompts the user and gives them the opportunity to satisfy the required Conditional Access policy. In certain cases when calling an API requiring Conditional Access, you can receive a claims challenge in the error from the API. For instance if the Conditional Access policy is to have a managed device (Intune) the error will be something like AADSTS53000: Your device is required to be managed to access this resource or something similar. In this case, you can pass the claims in the acquire token call so that the user is prompted to satisfy the appropriate policy. When calling an API requiring Conditional Access from MSAL.NET, your application needs to handle claim challenge exceptions. This appears as an MsalServiceException where the Claims property won't be empty. To handle the claim challenge, use WithClaims(String). ## Retrying after errors and exceptions You're expected to implement your own retry policies when calling MSAL. MSAL makes HTTP calls to the Microsoft Entra service, and occasionally failures can occur. For example the network can go down or the server is overloaded. ### HTTP 429 When the Service Token Server (STS) is overloaded with too many requests, it returns HTTP error 429 with a hint about how long until you can try again in the `Retry-After` response field. ### HTTP error codes 500-600 MSAL.NET implements a simple retry-once mechanism for errors with HTTP error codes 500-600. MsalServiceException surfaces `System.Net.Http.Headers.HttpResponseHeaders` as a property `namedHeaders`. You can use additional information from the error code to improve the reliability of your applications. In the case described, you can use the

Source URL

https://learn.microsoft.com/en-us/entra/msal/dotnet/advanced/exceptions/msal-error-handling?tabs=dotnet

Related Pain Points