azure-apimanagement

Azure API Management Troubleshooting

Quick Reference

Property	Value
Services	Azure API Management
MCP Tools	mcp_azure_mcp_apimanagement
Best For	Diagnosing gateway, policy, backend, and authentication issues

When to Use This Skill

• Gateway errors (502 Bad Gateway, 503 Service Unavailable) or backend connectivity failures
• Policy validation failures or policy expression errors
• API import errors (OpenAPI, WSDL, or other formats)
• Authentication issues (subscription key, JWT validation, certificate errors)
• CORS errors or preflight request failures
• Rate limiting, quota enforcement, or throttling problems
• API versioning, revision, or mocking configuration issues
• Named values, backend, or self-hosted gateway misconfiguration
• Developer portal customization or subscription problems
• Request tracing, diagnostics, or logging questions

MCP Tools

Tool	Command	Use
mcp_azure_mcp_apimanagement	Service/API ops	List services, APIs, products, policies, subscriptions
mcp_azure_mcp_monitor	logs_query	Query diagnostic logs with KQL
mcp_azure_mcp_resourcehealth	get	Check service health status
mcp_azure_mcp_documentation	Doc search	Search Microsoft Learn for troubleshooting docs

Diagnosis Workflow

1. Identify the API and revision — Check the prompt for API name, version, and revision clues; if not stated, proceed with diagnosis and ask later if needed
2. Check resource health — Use mcp_azure_mcp_resourcehealth to verify the API Management service is healthy
3. Review the error message — Match against the gateway, policy, backend, or auth troubleshooting guide
4. Enable request tracing — Use API Management trace to inspect policy execution and backend responses
5. Look up documentation — Use mcp_azure_mcp_documentation to search Microsoft Learn for the error or topic
6. Check configuration — Verify policies, named values, backend settings, subscription keys, and CORS configuration
7. Recommend fix — Apply remediation, citing documentation found

Troubleshooting Guides

Gateway, policy, backend, and authentication troubleshooting guides are located in the azure-diagnostics skill under troubleshooting/apimanagement/.

References

• Use mcp_azure_mcp_documentation to search Microsoft Learn for latest guidance.