I have an operation defined as POST /api/example in Azure API Management. When I send GET /api/example, APIM returns 404 Not Found instead of 405 Method Not Allowed. I would expect GET /api/does-not-exist to return 404, while GET /api/example—where the path exists but only POST is configured—would return 405, ideally with an Allow: POST header.
This makes gateway logs harder to interpret because a 404 could mean either that the URL is invalid or that the caller used the wrong HTTP method. The request appears to pass authentication before APIM generates the 404, so APIM seems to know which API was reached but fails during operation matching.
Is this intentional? Does APIM treat the path and HTTP method as one combined operation key, returning 404 whenever that exact combination is missing? Is there a setting or policy that enables more specific 405 responses, or is this simply how APIM's gateway is designed?
2 Answers
APIM does not appear to automatically return 405 for a valid path used with an unsupported method. Since it acts as the gateway or front door for a backend API, it resolves the incoming path and verb as a single operation match. If that exact operation is not found, the gateway returns 404. That is less specific than a 405, but it is still a deliberate behavior of the gateway rather than an indication that the backend resource itself is missing.
There are practical reasons a gateway might choose this behavior. Returning 405 would require the router to recognize that the path exists, continue checking other operations, and potentially construct an Allow header listing supported methods. Treating path and method as one lookup keeps routing simpler and avoids exposing which paths exist or which verbs are available. It also leaves related validation, such as unsupported media types, to the backend unless APIM is explicitly configured to enforce it.
I understand the performance and information-disclosure arguments, but the behavior is still confusing in diagnostics. In this case the request has already passed authentication, and APIM knows the API and path before producing its own 404. That makes it feel like a method mismatch is being hidden behind the same response used for a nonexistent URL. Since APIM owns the operation definitions, it seems like it would be in the best position to distinguish those cases, even if the default router intentionally does not.