What HTTP status to use?

Question

API

We have some RESTful API.

The client is authenticated and receives a token.
Further, to access certain pages, the client must provide this token.

What HTTP status should the server return if the token is not passed?
- 400 Bad Request (because the token is a required parameter)
- 401 Unauthorized
- 403 Forbidden

What if the wrong token is passed?

UPD
...or did the session for the passed token expire?

UPD 2
According to " Web Server Header Based Decision Diagram " from wikipedia, what happens is:


Can the absence of a parameter be considered a "Bad Request"?

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

RFC 2616 clause 10.4.1 its processing occurs before the authorization check.

Next, the server checks whether the client is authorized.
If the token is incorrect or missing (let's say we decided not to use the 400 code), then the server sends the 401 code - it asks for authorization.

Finally, the server recognized the user. There is access - we work further, no access - 403 status.

In addition, RFC 2616 says about status 403:

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

In other words:
400 or 401 if the token is not transferred
401 if the token is invalid / session expired
403 the token is transferred and the client is recognized but not able to access the content

Am I right?

Answer 1

403 for both situations, if there is a differentiation of rights, if just an identity check - 401

Answer 2

Is this fundamental or do you just want to do it as “correctly” as possible?)
I would choose 403 for both if not passed and for incorrect. If indeed the parameter is required at the API level, then 400 is possible for the missing one, but this is a moot point. And 401 is still conceived for another.

Answer 3

I would look at this from the point of view of a developer who connects to the API: in order to quickly and easily debug my error, the 401 Unauthorized status would help me the most.

Answer 4

For an auth request:
* 400 if no token was submitted at all
* 401 if invalid
For other pages:
* 403 if no token was submitted at all
* 403 if invalid

Answer 5

401 - not transmitted, 403 - invalid.

Answer 6

Invalid token - access denied.
HTTP/1.1 403 Forbidden?