MSC4178: Additional Error Codes for requestToken endpoint

proposals/4178-threepid-medium-not-supported.md

@@ -0,0 +1,44 @@
+# MSC4178: Error codes for requestToken
+
+There are a number of ways that sending a token to validate a third party identifier can go wrong.
+The requestToken API, however, has a very limited number of error codes that it can return.
+
+Firstly, homeservers may not always support adding email addresses or phone numbers to a user's account,
+however, there is no error code to signal this situation. Synapse currently returns `M_UNKNOWN`
+which leads to bad, untranslatable error messages.
+
+Secondly, the supplied third party identifier may be invalid.
+
+## Proposal
+
+Firstly, Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both
+[`/account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken)
+and
+[`/account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken),
+defined to mean that the homeserver does not support adding a third party identifier of that medium.
+
+Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party identifier parameter
+was not a valid identifier for that medium (eg. not a valid phone number).
+
+## Potential issues
+
+None forseen
+
+## Alternatives
+
+A better UX would be for servers to advertise what third party identifiers that support adding so that clients can
+inform users before they try to do so. This should be in addition rather than as alternative though: the clearest
+possible API will come from having both.
+
+## Security considerations
+
+None forseen
+
+## Unstable prefix
+
+This is sufficiently simple that proving it on a large scale is unnecessary. The code should not be used in the open
+before the MSC has been accepted.
+
+## Dependencies
+
+None