What's the right http status of locked user due to brute force attack?

Question

In case of brute force attack, what is the right status code that a REST api should return for a locked user? Actually, when a user fails password three times in last 3 minutes a lock its account.

If he try to login the fourth time, it receive a response with {"success":"false"} with status code 401. Is it formally right or not?

Answer 1

I'm a teapot

If you determine that your application is under attack, you could return 418 (I'm a teapot) and use a "short and stout" message in the response payload.

Unauthorized and forbidden

For HTTP authentication (stateless and sending the credentials in the Authorization header) use 401 (Unauthorized) to indicate that the credentials have been refused for that request.

Assuming that the credentials are valid but the user account is locked (or in any other condition that prevents the server from accepting the request), you could use 403 (Forbidden) and a descriptive message in the payload. Quote from the RFC 7235:

A server that receives valid credentials that are not adequate to gain access ought to respond with the 403 (Forbidden) status code.

Answer 2

403 Forbidden

403 means that "yes, I know about you, and your credentials might even be valid, but I am rejecting you anyway". Whether that be due to a lockout, your IP is banned, the phase of the moon isn't the correct one, etc, you can use this to signal that the request was invalid for that reason.