Extension: Problem Reporting

Here is an extension to OAuth, defining how a Service Provider can report problems to a Consumer. The enables the Consumer to provide a more satisfying experience to the User, by resolving the problem automatically or giving the User actionable advice for resolving the problem.

A Service Provider MAY report a failure by including the following parameters in any HTTP response. These parameters SHOULD be included in an OAuth WWW-Authenticate header (in accordance with OAuth section 5.4.2), and MAY also be included in the response body (in accordance with OAuth section 5.3). These parameters MAY be sent in both the header and body of the same response, in which case these parameters MUST be identical in these two places.

The parameter named oauth_problem is a positive number in decimal notation. The meanings of some values are:

• 1: the oauth_version isn't supported by the Service Provider. In this case, the response SHOULD also contain an oauth_acceptable_versions parameter (described below).
• 2: the oauth_consumer_key is unknown to the Service Provider.
• 3: the oauth_consumer_key is permanently unacceptable to the Service Provider. For example, the Consumer may be black listed.
• 4: the oauth_consumer_key is temporarily unacceptable to the Service Provider. For example, the Service Provider may be throttling the Consumer.
• 5: the oauth_token is unacceptable to the Service Provider. The reason is unspecified. It might mean that the token was never issued, or consumed or expired and then subsequently forgotten by the Service Provider.
• 6: the oauth_token has been consumed. That is, it can't be used any more because it has already been used in a previous request or requests.
• 7: the oauth_token has expired. That is, it was issued too long ago to be used now.
• 8: the oauth_signature_method is unacceptable to the Service Provider.
• 9: the oauth_timestamp value is unacceptable to the Service Provider. In this case, the response SHOULD also contain an oauth_acceptable_timestamps parameter (described below).
• 10: the oauth_nonce value was used in a previous request, and consequently can't be used now.

Other values of oauth_failure MUST NOT be used. However, a Consumer SHOULD be prepared to receive other values, from a Service Provider that implements a future version of this extension.

The parameter named oauth_acceptable_versions consists of two version numbers separated by '-' (hyphen). It represents the range of versions acceptable to the sender. That is, it means the sender will currently accept an oauth_version that's not older than the first number and not newer than the second number. A version A.B is considered greater than C.D if either A > C, or A = C and B > D.

The parameter named oauth_acceptable_timestamps consists of two numbers in decimal notation, separated by '-' (hyphen). It represents the range of timestamps acceptable to the sender. That is, it means the sender will currently accept an oauth_timestamp that's not smaller than the first number and not greater than the second number.

The parameter named oauth_problem_advice consists of free-form text intended to be read by the User. It SHOULD describe the problem in a way that's meaninful to the User, and suggest how to resolve the problem. The text MUST NOT contain HTML tags or any other form of markup.