Be explicit about failure conditions vs result in realtime vs rest libs

content/client-lib-development-guide/features.textile

@@ -99,11 +99,12 @@ h3(#rest-auth). Auth
 * @(RSA4)@ Token Auth is used if @useTokenAuth@ is set to true, or if @useTokenAuth@ is unspecified and any one of the following conditions are met: a @clientId@ is specified; @authUrl@ or @authCallback@ is provided; an explicit @token@ or @TokenDetails@ is provided
 ** @(RSA4a)@ When a @token@ or @tokenDetails@ is used to instance the library, and no means to renew the token is provided (either an API key, @authCallback@ or @authUrl@), if the server responds with a token error (401 HTTP status code and an Ably error value @40140 <= code < 40150@), then the client library should indicate an error, not retry the request and in the case of the realtime library, transition the connection to the @FAILED@ state
 ** @(RSA4b)@ When the client does have a means to renew the token automatically, and the token has expired or the server has responded with a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@), then the client should automatically make a single attempt to reissue the token and resend the request using the new token. If the token creation failed or the subsequent request with the new token failed due to a token error, then the request should result in an error
-** @(RSA4c)@ If an attempt by the realtime client library to authenticate is made using the @authUrl@ or @authCallback@, and the request to @authUrl@ fails, the callback @authCallback@ results in an error, the provided token is in an invalid format (per "RSA4d":#RSA4), or the attempt times out after "@realtimeRequestTimeout@":#DF1b, then:
-*** @(RSA4c1)@An @ErrorInfo@ with @code@ @80019@ and description of the underlying failure should be emitted with the state change, in the @errorReason@ and/or in the callback as appropriate
-*** @(RSA4c2)@If the connection is @CONNECTING@, then the connection attempt should be treated as unsuccessful, and as such the connection should transition to the @DISCONNECTED@ or @SUSPENDED@ state as defined in "RTN14":#RTN14 and "RTN15":#RTN15
-*** @(RSA4c3)@If the connection is @CONNECTED@, then the connection should remain @CONNECTED@
-** @(RSA4d)@ If an attempt to authenticate is made using the @authUrl@ and the content type is neither @text/plain@ or @application/json@, or if using @authCallback@ and the object passed in is neither a @String@, @JsonObject@, @TokenRequest@ object or a @TokenDetails@ object, the auth attempt should fail with error code @40170@ and a suitable error message.  Additionally, if the text token string is greater than 384 bytes, or the JSON stringified @JsonObject@, @TokenRequest@ or @TokenDetails@ is greater than 128kb, then the auth attempt should fail with error code @40170@ and a suitable error message.
+** @(RSA4c)@ If an attempt by the realtime client library to authenticate is made using the @authUrl@ or @authCallback@, and the request to @authUrl@ fails, the callback @authCallback@ results in an error, the provided token is in an invalid format (as defined in "RSA4e":#RSA4e), or the attempt times out after "@realtimeRequestTimeout@":#DF1b, then:
+*** @(RSA4c1)@ An @ErrorInfo@ with @code@ @80019@ and description of the underlying failure should be emitted with the state change, in the @errorReason@ and/or in the callback as appropriate
+*** @(RSA4c2)@ If the connection is @CONNECTING@, then the connection attempt should be treated as unsuccessful, and as such the connection should transition to the @DISCONNECTED@ or @SUSPENDED@ state as defined in "RTN14":#RTN14 and "RTN15":#RTN15
+*** @(RSA4c3)@ If the connection is @CONNECTED@, then the connection should remain @CONNECTED@
+** @(RSA4d)@ If an attempt to authenticate is made using the @authUrl@ or @authCallback@ as a result of a request that uses the REST API, or by an explicit call to @authorize@ or @requestToken@, and the request to @authUrl@ fails, the callback @authCallback@ results in an error, the provided token is in an invalid format (as defined in "RSA4e":#RSA4e), or the attempt times out after "@realtimeRequestTimeout@":#DF1b, then the request should fail with error code @40170@ and a suitable error message.
+** @(RSA4e)@ The following conditions imply that the token is in an invalid format: the @authUrl@ response content type is neither @text/plain@ nor @application/json@; the object passed by @authCallback@ is neither a @String@, @JsonObject@, @TokenRequest@ object, nor @TokenDetails@ object; the text token string is greater than 384 bytes; the JSON stringified @JsonObject@, @TokenRequest@ or @TokenDetails@ is greater than 128kb.
 * @(RSA14)@ If Token Auth is selected, yet a token is not provided and there is no means to generate a token, then this will result in an error. For example, if only the option @useTokenAuth@ is specified, and a @key@ is not provided, then the client library is unable to authenticate or issue a token
 * @(RSA15)@ If Token Auth is selected and @clientId@ has been set in the @ClientOptions@ when the library was instanced:
 ** @(RSA15a)@ Any @clientId@ provided in @ClientOptions@ must match any non wildcard (@'*'@) @clientId@ value in @TokenDetails@ or @connectionDetails@ of the @CONNECTED@ @ProtocolMessage@, where applicable