Add standard error responses (MSC3743). (#1347)

changelogs/application_service/newsfragments/1347.feature

@@ -0,0 +1 @@
+Add information on standard error responses for unknown endpoints/methods.

changelogs/client_server/newsfragments/1347.feature

@@ -0,0 +1 @@
+Add information on standard error responses for unknown endpoints/methods.

changelogs/identity_service/newsfragments/1347.feature

@@ -0,0 +1 @@
+Add information on standard error responses for unknown endpoints/methods.

changelogs/push_gateway/newsfragments/1347.feature

@@ -0,0 +1 @@
+Add information on standard error responses for unknown endpoints/methods.

changelogs/server_server/newsfragments/1347.feature

@@ -0,0 +1 @@
+Add information on standard error responses for unknown endpoints/methods.

content/application-service-api.md

@@ -164,6 +164,14 @@ each is as follows:
 Homeservers should periodically try again for the newer endpoints
 because the application service may have been updated.
 
+#### Unknown routes
+
+If a request for an unsupported (or unknown) endpoint is received then the server
+must respond with a 404 `M_UNRECOGNIZED` error.
+
+Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method
+to a known endpoint.
+
 #### Pushing events
 
 The application service API provides a transaction API for sending a

content/client-server-api/_index.md

@@ -107,6 +107,11 @@ No resource was found for this request.
 Too many requests have been sent in a short period of time. Wait a while
 then try again.
 
+`M_UNRECOGNIZED`
+The server did not understand the request. This is expected to be returned with
+a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
+code if the endpoint is implemented, but the incorrect HTTP method is used.
+
 `M_UNKNOWN`
 An unknown error has occurred.
 
@@ -116,9 +121,6 @@ The following error codes are specific to certain endpoints.
 
 <!-- TODO: move them to the endpoints that return them -->
 
-`M_UNRECOGNIZED`
-The server did not understand the request.
-
 `M_UNAUTHORIZED`
 The request was not correctly authorized. Usually due to login failures.
 

content/identity-service-api.md

@@ -108,6 +108,11 @@ attempting to verify ownership of a given third party address.
 The request contained an unrecognised value, such as an unknown token or
 medium.
 
+This is also used as the response if a server did not understand the request.
+This is expected to be returned with a 404 HTTP status code if the endpoint is
+not implemented or a 405 HTTP status code if the endpoint is implemented, but
+the incorrect HTTP method is used.
+
 `M_THREEPID_IN_USE`
 The third party identifier is already in use by another user. Typically
 this error will have an additional `mxid` property to indicate who owns

content/push-gateway-api.md

@@ -37,6 +37,16 @@ notification provider (e.g. APNS, GCM).
          Mobile Device or Client
 ```
 
+## API standards
+
+### Unsupported endpoints
+
+If a request for an unsupported (or unknown) endpoint is received then the server
+must respond with a 404 `M_UNRECOGNIZED` error.
+
+Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method
+to a known endpoint.
+
 ## Homeserver behaviour
 
 This describes the format used by "HTTP" pushers to send notifications

content/server-server-api.md

@@ -84,6 +84,14 @@ to be an IP address in which case SNI is not supported and should not be sent.
 Servers are encouraged to make use of the [Certificate
 Transparency](https://www.certificate-transparency.org/) project.
 
+### Unsupported endpoints
+
+If a request for an unsupported (or unknown) endpoint is received then the server
+must respond with a 404 `M_UNRECOGNIZED` error.
+
+Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method
+to a known endpoint.
+
 ## Server discovery
 
 ### Resolving server names