I have an operation defined as POST /api/example, but sending GET /api/example through Azure API Management returns 404 Not Found. Since the path exists and only the HTTP method is incorrect, I expected a 405 Method Not Allowed response, ideally with an Allow: POST header. A genuinely unknown path, such as GET /api/does-not-exist, should still return 404.
This makes gateway logs harder to interpret because the same 404 can mean either that the URL is invalid or that the caller used the wrong verb. In my case, the request passes authentication before APIM generates the 404, so APIM appears to know which API was reached but fails during operation matching.
Is this expected APIM behavior, perhaps because it treats the method and path as one operation key? Is there a configuration option to return 405 instead, or does APIM intentionally collapse these cases into 404?
2 Answers
There are practical reasons a gateway might choose this behavior. Distinguishing the cases can require additional route checks, and a 405 response commonly includes an Allow header listing supported methods. That adds processing and also reveals that a resource exists, which some systems prefer not to expose.
It also keeps responsibility boundaries simple: APIM resolves registered operations, while the backend can handle more detailed HTTP semantics such as 405 or 415 when appropriate. APIM has tracing and API specifications for diagnosing method mismatches, so the demand for automatic 405 handling may not have been considered high enough to justify different routing behavior.
APIM does not appear to automatically generate 405 responses for a valid path with an unsupported method. Since it acts as a gateway or proxy in front of the actual API, it treats the complete method-and-path combination as the operation lookup key. If that combination is not registered, the gateway returns 404. It may be less specific than 405, but it is the behavior the service uses.
Technically correct, perhaps, but not very helpful when the same response can mean either a nonexistent route or a valid route called with the wrong verb.
That makes sense as a design trade-off, but APIM has already authenticated the request and knows the API and path involved before producing the 404. From an operations standpoint, returning the same status as a nonexistent URL still loses useful information. Since APIM owns the operation table, it seems particularly well positioned to distinguish a missing path from an unsupported method.