In Azure API Management, when the HTTP method of a request doesn’t match the one defined in the corresponding operation, APIM returns status code
HTTP 404 Resource Not Found to the client. For example, the OOTB Echo API defined the Retrieve resource (cached) operation with HTTP GET. If you call it with HTTP POST, you’ll get
HTTP 404 Resource Not Found in the response.
The HTTP 404 returned by APIM in this scenario doesn’t really follow the definition of HTTP status code strictly. According to the definition,
HTTP 405 Method Not Allowed is designated for this situation. There was a feedback for this issue to APIM team and it would be addressed in the future according to the response. But before that, we have to use some workaround to bypass this issue. Here is how you can do it with policies in APIM.
Handle the error
When APIM failed to identify an API or operation, it will raise a configuration error which will returns HTTP 404. What we need to do is to handle this error and change the status code to HTTP 405. In this way, you avoid the overhead of creating operations for each of the HTTP methods to handle the situation. The next question is on which scope the error should be handled. Depending on the configurations of your APIM, I think you can handle the error on either all operations or all APIs.
The policy code
The following policy code is a sample for Echo API all operations.
<when condition="@(context.LastError.Source == "configuration" && context.Request.Url.Path == "/echo/resource-cached")">
<set-status code="405" reason="Method not allowed" />
return new JObject(
new JProperty("status", "HTTP 405"),
new JProperty("message", "Method not allowed")
The tricky part is in the
<when> condition. The first part of the condition is to check if this is a configuration error. If it is, the second part will test if the request is to Retrieve resource (cached) operation. The second test is to avoid the situation where a real HTTP 404 happens.
You may wonder why I used
context.Request rather than
context.Operation to test which operation it is. The reason is APIM sets
context.Operation to null in this case because it cannot identify which operation it is (and that is why the configuration error happens).
You can use this walkaround to return HTTP 405 until APIM fixes its behavior.
Update: The above sample code has been merged to the Azure API Management Policy Snippets.