What's the good http status code to return on

Question

When a password is expired what rest api should return? I mean: username and password are correct, but expired.

Here I found that

The mechanisms for expiring or revoking credentials can be specified as part of an authentication scheme definition.

Is there a specification about what's the right and/or correct http status code for expired credentials? Is http status code good to handle with credentials expiration?

Answer 1

An expired password is an invalid password and must not be accepted by the server.

So if you are using HTTP authentication (sending credentials in the Authorization header), you can use 401 with a descriptive payload.

Here are some quotes from the RFC 7235, the reference for authentication in HTTP/1.1:

4.2. Authorization

The Authorization header field allows a user agent to authenticate itself with an origin server -- usually, but not necessarily, after receiving a 401 (Unauthorized) response. Its value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.

 Authorization = credentials

[...]

3.1. 401 Unauthorized

The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.

If the request included authentication credentials, then the 401 response indicates that authorization has been refused for those credentials. [...]

Answer 2

http://getstatuscode.com/419

Not a part of the HTTP standard, 419 Authentication Timeout denotes that previously valid authentication has expired. It is used as an alternative to 401 Unauthorized in order to differentiate from otherwise authenticated clients being denied access to specific server resources.