Look for registration service errors in response bodies in addition to status responses

service/src/main/proto/RegistrationService.proto

@@ -50,6 +50,12 @@ message RegistrationSessionMetadata {
    * session associated with this registration attempt.
    */
   bytes session_id = 1;
+
+  /**
+   * Indicates whether a valid verification code has been submitted in the scope
+   * of this session.
+   */
+  bool verified = 2;
 }
 
 message CreateRegistrationSessionError {
@@ -59,37 +65,39 @@ message CreateRegistrationSessionError {
   CreateRegistrationSessionErrorType error_type = 1;
 
   /**
-   * Indicates that this error is fatal and should not be retried without
-   * modification. Non-fatal errors may be retried without modification after
-   * the duration indicated by `retry_after_seconds`.
+   * Indicates that this error may succeed if retried without modification after
+   * a delay indicated by `retry_after_seconds`. If false, callers should not
+   * retry the request without modification.
    */
-  bool fatal = 2;
+  bool may_retry = 2;
 
   /**
-   * If this error is not fatal (see `fatal`), indicates the duration in seconds
-   * from the present after which the request may be retried without
-   * modification. This value has no meaning otherwise.
+   * If this error may be retried,, indicates the duration in seconds from the
+   * present after which the request may be retried without modification. This
+   * value has no meaning otherwise.
    */
   uint64 retry_after_seconds = 3;
 }
 
 enum CreateRegistrationSessionErrorType {
-  ERROR_TYPE_UNSPECIFIED = 0;
+  CREATE_REGISTRATION_SESSION_ERROR_TYPE_UNSPECIFIED = 0;
 
   /**
    * Indicates that a session could not be created because too many requests to
    * create a session for the given phone number have been received in some
    * window of time. Callers should wait and try again later.
    */
-  ERROR_TYPE_RATE_LIMITED = 1;
+  CREATE_REGISTRATION_SESSION_ERROR_TYPE_RATE_LIMITED = 1;
+
+  /**
+   * Indicates that the provided phone number could not be parsed.
+   */
+  CREATE_REGISTRATION_SESSION_ERROR_TYPE_ILLEGAL_PHONE_NUMBER = 2;
 }
 
 message SendVerificationCodeRequest {
-  /**
-   * The phone number to which to send a verification code. Ignored (and may be
-   * null if `session_id` is set.
-   */
-  uint64 e164 = 1;
+
+  reserved 1;
 
   /**
    * The message transport to use to send a verification code to the destination
@@ -112,6 +120,12 @@ message SendVerificationCodeRequest {
    * The ID of a session within which to send (or re-send) a verification code.
    */
   bytes session_id = 5;
+
+  /**
+   * If provided, always attempt to use the specified sender to send
+   * this message.
+   */
+  string sender_name = 6;
 }
 
 enum MessageTransport {
@@ -133,6 +147,76 @@ message SendVerificationCodeResponse {
    * session associated with this registration attempt.
    */
   bytes session_id = 1;
+
+  /**
+   * Metadata for the named session. May be absent if the session could not be
+   * found or has expired.
+   */
+  RegistrationSessionMetadata session_metadata = 2;
+
+  /**
+   * If a code could not be sent, explains the underlying error. Will be absent
+   * if a code was sent successfully. Note that both an error and session
+   * metadata may be present in the same response because the session metadata
+   * may include information helpful for resolving the underlying error (i.e.
+   * "next attempt" times).
+   */
+  SendVerificationCodeError error = 3;
+}
+
+message SendVerificationCodeError {
+  /**
+   * The type of error that prevented a verification code from being sent.
+   */
+  SendVerificationCodeErrorType error_type = 1;
+
+  /**
+   * Indicates that this error may succeed if retried without modification after
+   * a delay indicated by `retry_after_seconds`. If false, callers should not
+   * retry the request without modification.
+   */
+  bool may_retry = 2;
+
+  /**
+   * If this error may be retried,, indicates the duration in seconds from the
+   * present after which the request may be retried without modification. This
+   * value has no meaning otherwise.
+   */
+  uint64 retry_after_seconds = 3;
+}
+
+enum SendVerificationCodeErrorType {
+  SEND_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;
+
+  /**
+   * The sender received and understood the request to send a verification code,
+   * but declined to do so (i.e. due to rate limits or suspected fraud).
+   */
+  SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_REJECTED = 1;
+
+  /**
+   * The sender could not process or would not accept some part of a request
+   * (e.g. a valid phone number that cannot receive SMS messages).
+   */
+  SEND_VERIFICATION_CODE_ERROR_TYPE_SENDER_ILLEGAL_ARGUMENT = 2;
+
+  /**
+   * A verification could could not be sent via the requested channel due to
+   * timing/rate restrictions. The response object containing this error should
+   * include session metadata that indicates when the next attempt is allowed.
+   */
+  SEND_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 3;
+
+  /**
+   * No session was found with the given ID.
+   */
+  SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 4;
+
+  /**
+   * A new verification could could not be sent because the session has already
+   * been verified.
+   */
+  SEND_VERIFICATION_CODE_ERROR_TYPE_SESSION_ALREADY_VERIFIED = 5;
 }
 
 message CheckVerificationCodeRequest {
@@ -153,4 +237,70 @@ message CheckVerificationCodeResponse {
    * matched the expected code or false otherwise.
    */
   bool verified = 1;
+
+  /**
+   * Metadata for the named session. May be absent if the session could not be
+   * found or has expired.
+   */
+  RegistrationSessionMetadata session_metadata = 2;
+
+  /**
+   * If a code could not be checked, explains the underlying error. Will be
+   * absent if no error occurred. Note that both an error and session
+   * metadata may be present in the same response because the session metadata
+   * may include information helpful for resolving the underlying error (i.e.
+   * "next attempt" times).
+   */
+  CheckVerificationCodeError error = 3;
+}
+
+message CheckVerificationCodeError {
+  /**
+   * The type of error that prevented a verification code from being checked.
+   */
+  CheckVerificationCodeErrorType error_type = 1;
+
+  /**
+   * Indicates that this error may succeed if retried without modification after
+   * a delay indicated by `retry_after_seconds`. If false, callers should not
+   * retry the request without modification.
+   */
+  bool may_retry = 2;
+
+  /**
+   * If this error may be retried,, indicates the duration in seconds from the
+   * present after which the request may be retried without modification. This
+   * value has no meaning otherwise.
+   */
+  uint64 retry_after_seconds = 3;
+}
+
+enum CheckVerificationCodeErrorType {
+  CHECK_VERIFICATION_CODE_ERROR_TYPE_UNSPECIFIED = 0;
+
+  /**
+   * The caller has made too many incorrect guesses within the scope of this
+   * session and may not make any further guesses.
+   */
+  CHECK_VERIFICATION_CODE_ERROR_TYPE_ATTEMPTS_EXHAUSTED = 1;
+
+  /**
+   * The caller has attempted to submit a verification code even though no
+   * verification codes have been sent within the scope of this session. The
+   * caller must issue a "send code" request before trying again.
+   */
+  CHECK_VERIFICATION_CODE_ERROR_TYPE_NO_CODE_SENT = 2;
+
+  /**
+   * The caller has made too many guesses within some period of time. Callers
+   * should wait for the duration prescribed in the session metadata object
+   * elsewhere in the response before trying again.
+   */
+  CHECK_VERIFICATION_CODE_ERROR_TYPE_RATE_LIMITED = 3;
+
+  /**
+   * The session identified in this request could not be found (possibly due to
+   * session expiration).
+   */
+  CHECK_VERIFICATION_CODE_ERROR_TYPE_SESSION_NOT_FOUND = 4;
 }