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?

Posterior

As for me 401 is slightly more suitable here – Moazami

doesn't 401 mean credentials are valid but is not authorized to access the resource ( e.g. normal user trying to access admin specific API) – Posterior

Have read your ref1/ref2. 403 confuses me as potential consumer of your api. According to it: "Authorization will not help and the request SHOULD NOT be repeated.". So I reauthorization shouldn't help me. And 400 is just general error which cover the details. Than You have to add specific message/header which is not the best choice – Moazami

yes I did read them before posting questions here, uncertainty about 401/403 for the mentioned scenario lead me to go with 400 bad reques which I am not sure is still best choice, so yes I am looking for information which code is more suitable here and how – Posterior

Well at the end its up to you. :) In all our cases we use 401 as an signal that we (again) want to receive credentials. – Moazami

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.

Feet

Answer 2

Works Around... Thinking about expired password (not exactly expired credencial) I found this from https://developer.mozilla.org/en-US/docs/Web/HTTP/Status 403 Forbidden The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. //- - - - Well I think the better is response with 403 with description or custom content header, and so the client need to call the endpoint with your auth + param with new password.

Now, about expired credencial (yet thinking about user and password, not token), 403 I think good too, because "the client's identity is known to the server" but unauthorized.

About token and your timestamp, 401 with description is good I think, because one of first steps is the server see the timestamp, and the timestamp will fail before checking any credentials..

Cognoscenti