From 824ce22caaae00a76f8d965f575197995c245903 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Fri, 31 Aug 2018 11:41:46 -0600
Subject: [PATCH] Add additional clarity to the requestToken errors

---
 api/client-server/administrative_contact.yaml |  8 ++--
 api/client-server/registration.yaml           | 48 ++++++++++++++++++-
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index 2fba9540..ddfbe172 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -282,12 +282,12 @@ paths:
             }
         400:
           description: |-
-            The homeserver was unable to locate a user with the third party identifier
-            already bound, or the request was invalid.
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
             application/json: {
-              "errcode": "M_THREEPID_NOT_FOUND",
-              "error": "Third party identifier not found"
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "Third party identifier already in use"
             }
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index 7b1230cb..b935b4f7 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -406,9 +406,31 @@ paths:
                 required: ['id_server']
       responses:
         200:
-          description: An email was sent to the given address
+          description: An email was sent to the given address.
           schema:
             $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not permit the user from having the third party
+            identifier as a contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Email not found"
+            }
   "/account/password/msisdn/requestToken":
     post:
       summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
@@ -420,7 +442,7 @@ paths:
         `account/password` endpoint. This API's parameters and response are
         identical to that of the HS API |/register/msisdn/requestToken|_ except that
         `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given email address could be found. The server may instead send an
+        given phone number could be found. The server may instead send an
         SMS message to the given address prompting the user to create an account.
         `M_THREEPID_IN_USE` may not be returned.
 
@@ -449,6 +471,28 @@ paths:
           description: An SMS message was sent to the given phone number.
           schema:
             $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not permit the user from having the third party
+            identifier as a contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Phone number not found"
+            }
   "/account/deactivate":
     post:
       summary: "Deactivate a user's account."