[FEATURE]: Provide guidance for handling failures to access a protected resource

[dave-shawley]

Is there an existing ticket for this?

• [X] I have searched the existing tickets

Is your feature request related to a problem? Please describe

Handling token-related failures to access a protected resource is difficult since there number of error values is limited. Consider the following two error responses for a token related failure.

{
  "error": "invalid_token",
  "error_description": "access token is expired"
}

and

{
  "error": "invalid_token",
  "error_description": "access token is invalid"
}

The requestor should refresh the access token in the first case and re-establish the customer connection in the second case. The key error indicator for OAuth resource responses is the error which is somewhat limited.

Describe the solution you'd like

Provide guidance on how to disambiguate error responses inside of computer programs.

RFC-6749 established a registry of well-known values that the OAuth-related responses can use for the error value. The registry is maintained by the IETF and published by the IANA:

https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#extensions-error

The API could be changed to return expired_token for expired access tokens and continue to return invalid_token in the case where the token is actually invalid.

Describe any alternatives you've considered

The other option that I considered was using well-known error_uri values. RFC-6749 includes the optional error_uri parameter which is described in section 5.2 as:

A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.

You could use the error_uri to indicate the specific error as well as target a "help" page as long as the URI doesn't change. For example, you could document the behavior at "https://developers.etsy.com/documentation/essentials/requests#auth-expired" and then use that as the well-known error_uri in the error response bodies. This would allow for error responses like the following to be clearly differentiated by the requestor.

{
  "error": "invalid_token",
  "error_description": "access token is expired",
  "error_uri": "https://developers.etsy.com/documentation/essentials/requests#auth-expired"
}

and

{
  "error": "invalid_token",
  "error_description": "access token is invalid",
  "error_uri": "https://developers.etsy.com/documentation/essentials/requests#auth-bad-token"
}

Additional context

My current codebase looks for the word "expired" in the error_description to disambiguate the two cases.

I posed this question in the etsy-api-v2 Google group as well -- https://groups.google.com/g/etsy-api-v2/c/UlE-jlBglcE/m/DFrdV8LUAAAJ