Azure API Management troubleshooting

Troubleshooting Azure API Management

Common errors

Below are some of the most frequently encountered errors and recommended remediation steps.

Error	Message	Resolution
502	Bad Gateway	Check upstream service health and ensure the backend URL is reachable.
504	Gateway Timeout	Increase timeout policy or investigate network latency.
401	Unauthorized	Validate subscription keys or OAuth token configuration.

Diagnostics & logs

Enable diagnostics to capture detailed request/response data.

az apim logger create \
  --resource-group myRG \
  --service-name myAPIM \
  --logger-name myLog \
  --type applicationinsights \
  --instrumentation-key <APP_INSIGHTS_KEY>

Then associate the logger with a diagnostic setting:

az apim diagnostic create \
  --resource-group myRG \
  --service-name myAPIM \
  --api-id myApi \
  --logger-id myLog \
  --sampling 100 \
  --always-log all-errors

Performance issues

Review cache-lookup and cache-store policies to reduce latency.
Scale the gateway tier (Developer → Standard → Premium) based on traffic patterns.
Enable request throttling to protect backend services.

Gateway connectivity

Validate DNS resolution and firewall rules for the .azure-api.net endpoint.

nslookup <your-apim-name>.azure-api.net

Test connectivity from a VM in the same region:

curl -v https://<your-apim-name>.azure-api.net/status

Policy troubleshooting

Use the trace feature in the Azure portal to view policy execution.

Sample policy that captures request headers for debugging:

<inbound>
  <base/>
  <log-to-eventhub logger-id="eventHubLogger">
    <message>Headers: @(string.Join(", ", context.Request.Headers.Select(h => h.Key + "=" + h.Value)))</message>
  </log-to-eventhub>
</inbound>