Clarification required on usage of UNAUTHENTICATED and AUTHENTICATION_REQUIRED error codes

[eric-murray]

Problem description
The API guidelines currently define two 401 error response codes, UNAUTHENTICATED and AUTHENTICATION_REQUIRED. It is not clear if these are synonyms, or if they correspond to different error scenarios.

Expected action
The usage of these two error codes should be clarified.

• Either remove one, combining them into a single 401 error response code; or
• Clarify the different error scenarios to which they correspond

My proposal would be:

AUTHENTICATION_REQUIRED: The access token lifetime has expired. This should be the most common error scenario.
UNAUTHENTICATED: The access token is either missing, is not and never was a valid access token (e.g. a random string, or an access token issued by a different API provider), or has been revoked or otherwise invalidated (e.g. if reported as having been leaked or stolen).

However, I'm also happy just to have a single 401 error code

Additional context

[sachinvodafone]

I agree with your last suggestion, @eric-murray. It makes more sense to use a single error code, like 401 UNAUTHORIZED, rather than having both UNAUTHENTICATED and AUTHENTICATION_REQUIRED, since they essentially convey the same meaning. Personally, seeing either of these codes doesn't provide much clarity, as they don't offer much insight on their own without further details.

[Kevsy]

401 Unauthorized covers both a lack of authentication credentials and invalid credentials, and an error message can convey what action is required to retry - so I think just 401 can cover it (although it's not ideal that the status code name is Unauthorized - which is rather the scope of 403 Forbidden - instead of Unauthenticated).

[PedroDiez]

Hi, both approaches work with us.

In order to simplify, our proposal is to keep 401 - UNAUTHENTICATED