what should be HTTP status code for credentials Expired error/exception?

Question

I am developing RESTful APIs, I have implemented token-based authentication, where token digest is prepared using time-stamp. Now when request comes to API server, I am checking if the supplied time-stamp is invalid ( i.e. date-time from future/past is specified) then am throwing error message indicating that "future token detected" or "token has expired". I need to attach HTTP status code I am confused about which status code is suitable for this situation?

I have gone through the status codes available (ref1, ref2) so far, I think, using 400 'bad request' will be suitable here instead of 401 'Unauthorized' and 403 'forbidden' status codes.

what do you think guys?

Answer 1

As the timestamp is invalid, I think the token is invalid. So the client is not authenticated anymore. So I would throw a 401 Unauthorized. You're free to add extra data of the context as HTTP header with the X- prefix, or to add a response body encoded according to the Accept request header (json, text, etc.). Like:

{
  "error": {
    "status": 401,
    "details": {
      "code": "401.3",
      "description": "The timestamp provided must not be in the future."
    }
  }
}

It is not a 403 Forbidden : 403 means "the client is authenticated but does not have the right to send this request". In your case, I think the client is not authenticated any more.