How to Troubleshoot Azure API Management (Complete Fix Guide)

The single biggest mistake teams make with Azure API Management troubleshooting is trying to debug in the dark. The portal test console helps for one-off requests, but for intermittent failures or production traffic analysis, you need persistent logging connected to Azure Monitor and Application Insights.

Go to your APIM instance in the Azure portal. In the left sidebar, under Monitoring, click Diagnostic settings. Click Add diagnostic setting. Give it a name like apim-diagnostics-prod. Under Category groups, check both GatewayLogs and allMetrics. Send these to a Log Analytics workspace, if you don't have one, create one now in the same region as your APIM instance.

Now wire up Application Insights. In the left sidebar, under Deployment and infrastructure, click Application Insights. Toggle Enable Application Insights to on, and select your Application Insights resource. Set the Sampling percentage to 100% for troubleshooting (you can reduce it later for cost management). Enable Log errors and Log all requests.

Once connected, open Application Insights and navigate to Failures in the left menu. You'll see a breakdown of failed operations with full request and response details, dependency traces to your backend, and exception stacks when policies throw errors. In Log Analytics, run this KQL query to see all gateway errors from the last hour:

ApiManagementGatewayLogs
| where TimeGenerated > ago(1h)
| where IsRequestSuccess == false
| project TimeGenerated, OperationName, ResponseCode, BackendResponseCode, LastErrorMessage, ClientIp
| order by TimeGenerated desc

If this query returns results, you now have the LastErrorMessage column, the internal error the gateway generated, which is never exposed to the calling client. This is where you'll find the real answer.

A 401 Unauthorized in Azure API Management can come from three completely different places, and the fix for each is entirely different. I know this is frustrating, the same HTTP status code masks very different root causes, and the error body often doesn't help.

Cause A: Missing or invalid subscription key. Navigate to APIs → select your API → Settings tab. Look at the Subscription section. If Subscription required is checked, every caller must include a valid key. Verify the key header name, by default it's Ocp-Apim-Subscription-Key, but it can be customized. Also confirm the subscription is Active (not Suspended) by going to Subscriptions in the left sidebar and checking the state column.

Cause B: JWT validation policy failure. Open the policy editor for the failing API (APIs → your API → Design tab → click the </> icon under Inbound processing). Look for a <validate-jwt> element. Common failures here include:

<validate-jwt header-name="Authorization" failed-validation-httpcode="401">
  <openid-config url="https://login.microsoftonline.com/{tenant-id}/.well-known/openid-configuration"/>
  <required-claims>
    <claim name="aud">
      <value>api://your-app-id</value>
    </claim>
  </required-claims>
</validate-jwt>

Check that the aud claim value exactly matches your registered application's App ID URI. A trailing slash difference or a mismatched GUID will cause a 401 every time. Enable tracing (Step from the Quick Fix section) and look for the validate-jwt node in the trace, it will show you exactly which claim validation failed.

Cause C: IP filtering or rate limit policy generating a 403. Search the policy XML for <ip-filter> or <quota> elements. A 403 from an IP filter means the caller's IP isn't in the allow list. The client IP as seen by the gateway is logged in ClientIp in GatewayLogs, cross-reference this against your filter list.

A 502 from Azure API Management means the gateway reached your backend but couldn't get a valid response back. This is different from a 503, which means the gateway couldn't connect at all. Understanding that distinction saves you from looking in the wrong place.

First, verify the backend URL is correct. Go to Backends in the left sidebar (or APIs → your API → Settings → Backend section). Look at the Service URL. Common issues: HTTP vs HTTPS mismatch, missing trailing slash causing double-slash in constructed URLs, or a URL that points to a hostname that resolves differently from inside Azure's network than from your developer machine.

For backend services hosted in an Azure Virtual Network, this is where things get complicated fast. If your APIM instance is in External VNet or Internal VNet mode, the gateway needs network line-of-sight to your backend. Use the built-in Network Connectivity Check tool, in the left sidebar under Deployment and infrastructure, click Network connectivity. This tool probes the backend endpoint from the gateway's network context and tells you if connectivity or DNS resolution is failing.

If your backend uses a self-signed TLS certificate or a private CA, the gateway will reject it by default. To bypass certificate validation during troubleshooting (never leave this in production), add this to your backend policy:

<set-backend-service backend-id="your-backend"/>
<!-- In the backend entity, set -->
<tls>
  <validate-certificate-chain>false</validate-certificate-chain>
  <validate-certificate-name>false</validate-certificate-name>
</tls>

Or configure this through the portal by going to Backends → select your backend → under TLS settings, uncheck Validate certificate chain and Validate certificate name for testing. If this fixes the 502, your real fix is uploading the correct CA certificate to Certificates in the APIM instance and referencing it properly.

Check the BackendResponseCode in your GatewayLogs query from Step 1. If it shows a 500 from the backend, the issue isn't APIM, the backend service itself is throwing an error, and you need to look at the backend application logs directly.

Policy errors are the trickiest category of Azure API Management issues because they can produce completely misleading HTTP responses. A broken set-header policy might silently swallow a request. A malformed send-request policy might cause a 500 that looks like a backend crash. The Azure portal has a dedicated policy debugger tool that most teams haven't found yet.

Navigate to APIs → select your API → click Debug in the top navigation (next to Test and Design). This opens the Policy Debugger, a step-through debugger that executes your policies in real time, showing you the exact state of the request context at each policy step. You can inspect context variables, header values, and body content at every point in the pipeline.

For finding broken policy XML without the debugger, open the policy editor and look for these common mistakes:

<!-- BROKEN: Named value referenced incorrectly -->
<set-header name="Authorization">
  <value>Bearer {{backend-token}}</value>  <!-- Wrong: use {{named-value}} syntax -->
</set-header>

<!-- CORRECT -->
<set-header name="Authorization">
  <value>@("Bearer " + context.Variables["backend-token"])</value>
</set-header>

Named value references use double curly braces {{my-named-value}} in static strings, but inside C# expressions (anything inside @()), you access named values through context.Variables["key"] or (string)context.Variables["key"]. Mixing these up is extremely common and generates policy compilation errors that are logged in GatewayLogs under LastErrorMessage as "Expression evaluation failed".

To validate all named values actually exist, go to Named values in the left sidebar and confirm every name referenced in your policies appears in that list. A named value that was deleted but is still referenced in a policy will cause every request through that API to fail with a 500-level error, not a configuration warning at deploy time.

After any policy change, force a cache refresh by going to APIs, clicking the ... menu on your API, and selecting Publish if available, or simply wait 30 seconds for policy changes to propagate to all gateway units.

A 429 Too Many Requests response from Azure API Management means a rate limiting or quota policy has been triggered. Unlike most other errors, this one is working as designed, but "working as designed" isn't helpful if the limit is too aggressive, wrongly scoped, or the counter reset interval is misconfigured.

Find the throttling policy causing the issue. In your policy XML, search for <rate-limit>, <rate-limit-by-key>, <quota>, or <quota-by-key>. These can appear at the global level, product level, API level, or operation level, check all four layers because a stricter policy at a higher scope overrides more permissive policies below it.

A common misconfiguration looks like this, a product-level rate limit that's actually lower than the operation-level limit intended for internal callers:

<!-- Product-level policy (applied first, overrides API-level) -->
<rate-limit calls="10" renewal-period="60" />

<!-- API-level policy (never actually effective for calls over 10/min) -->
<rate-limit-by-key calls="1000" renewal-period="60"
  counter-key="@(context.Subscription.Id)" />

To check current rate limit counters and understand which subscriptions are hitting limits, query Log Analytics:

ApiManagementGatewayLogs
| where TimeGenerated > ago(1h)
| where ResponseCode == 429
| summarize RequestCount = count() by ClientIp, tostring(SubscriptionId), bin(TimeGenerated, 5m)
| order by RequestCount desc

If legitimate traffic is being throttled, you have two fixes. For subscription-scoped limits: go to Products → select the product → Policies and increase the calls value or extend the renewal-period. For key-based limits: update the <rate-limit-by-key> policy and consider using a more granular counter key like context.Request.IpAddress to limit by client IP rather than by subscription, which distributes the quota more fairly across multiple callers sharing one subscription.

The 429 response from APIM includes a Retry-After header indicating how many seconds until the counter resets. Make sure your client applications are reading and respecting this header rather than hammering the gateway and making the situation worse.