Create troubleshooting.md

Author: santiagxf

articles/ai-foundry/model-inference/includes/configure-entra-id/troubleshooting.md

@@ -0,0 +1,17 @@
+---
+manager: nitinme
+author: santiagxf
+ms.author: fasantia 
+ms.service: azure-ai-model-inference
+ms.date: 01/23/2025
+ms.topic: include
+---
+
+The following table contains multiple scenarios that can help troubleshooting Microsoft Entra ID:
+
+| Error / Scenario | Root cause | Solution |
+| ---------------- | ---------- | -------- |
+| `401 Principal does not have access to API/Operation` | The request indicates authentication in the correct way, however, the user principal doesn't have the required permissions to use the inference endpoint. | Ensure you have: <br /> 1. Assigned the role **Cognitive Services User** to your principal to the Azure AI Services resource. <br /> 2. Wait at least 5 minutes before making the first call. |
+| `401 HTTP/1.1 401 PermissionDenied` | The request indicates authentication in the correct way, however, the user principal doesn't have the required permissions to use the inference endpoint. | Assigned the role **Cognitive Services User** to your principal in the Azure AI Services resource. Roles like **Administrator** or **Contributor** don't grand inference access. Wait at least 5 minutes before making the first call. |
+| `401 Unauthorized. Access token is missing, invalid, audience is incorrect (https://cognitiveservices.azure.com), or have expired.` | The request is failing to perform authentication with Entra ID as expected. The root case may be related with: <br /> 1. The request is not passing the tokens as part of the `Authentication` header. <br /> 2. The request is passing a token in the `Authentication` header, but the scope is incorrect. 3. The request is using an expired token. | Ensure the following: <br /> 1. If you are using REST API calls, ensure that the token is passes under the `Authentication` header with an scope `https://cognitiveservices.azure.com/.default`. <br /> 2. If you are using `AzureOpenAI` class from an SDK, ensure that you are using an **OpenAI model** connected to the endpoint `https://<resource>.openai.azure.com`. You can't use `OpenAI` class or a non Azure OpenAI model. If your model is not from OpenAI, use the Azure AI Inference SDK. <br /> If you're using the Azure AI Inference SDK, ensure you are connected to the endpoint `https://<resource>.services.ai.azure.com/model`. You can use this endpoint with all the model providers. |
+| `404 Not found` | The endpoint URL is incorrect based on the SDK you are using, or the model deployment doesn't exist. | Ensure you are using the right SDK connected to the right endpoint: <br /> 1. If you are using the Azure AI inference SDK, ensure the endpoint is `https://<resource>.services.ai.azure.com/model` with `model=<model-deployment-name` in the payloads, or endpoint is `https://<resource>.openai.azure.com/deployments/<model-deployment-name>` without the parameter `model` in the payload. <br /> If you are using the `AzureOpenAI` class, ensure the endpoint is `https://<resource>.openai.azure.com`. |