Troubleshooting Azure AI Services

Typical errors: 401 Unauthorized, 403 Forbidden, Invalid API key.

1. Verify your Azure AD token or API key matches the resource.
2. Ensure the resource principal has cognitive services user role.
3. Check the Endpoint URL is correct and region‑specific.

curl -X POST "https://{region}.api.cognitive.microsoft.com/face/v1.0/detect" \
-H "Ocp-Apim-Subscription-Key: <YOUR_KEY>" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/image.jpg"}'

Copy

Common messages: ModelNotFound, QuotaExceeded, ServiceUnavailable.

• Confirm the model name/version is correctly specified.
• Check resource quota in the Azure portal under Limits & Quotas.
• Restart the deployment from the Models page if stuck.

az cognitiveservices account show \
--name MyAIResource \
--resource-group MyGroup

Copy

High latency can be caused by network, request size, or endpoint throttling.

• Enable Batch requests where supported.
• Compress image payloads before sending.
• Use regional endpoints closest to your users.

Example of enabling async batch for OCR:

POST https://{region}.api.cognitive.microsoft.com/vision/v3.2/read/analyze
Headers:
  Ocp-Apim-Subscription-Key: <key>
Body:
  { "url": "https://example.com/document.pdf" }

Copy

When hitting quotas, Azure returns 429 Too Many Requests.

1. Review usage in the Azure portal under Metrics → Calls.
2. Request a quota increase via Support.
3. Implement exponential back‑off in your retry logic.

function retryRequest(url, options, attempt = 1) {
  return fetch(url, options).then(res => {
    if (res.status === 429 && attempt <= 5) {
      const delay = Math.pow(2, attempt) * 1000;
      return new Promise(r => setTimeout(r, delay))
        .then(() => retryRequest(url, options, attempt + 1));
    }
    return res;
  });
}

Copy

Why is my request returning “Invalid JSON”?

Ensure the payload uses double quotes and that special characters are escaped.

How do I rotate API keys?

Navigate to the resource → Keys and Endpoint, generate a new key, update your applications, then delete the old key.

Can I use Azure AI Services from on‑premises?

Yes, via the public endpoint or through Azure Private Link for secure connectivity.