The 409 (Conflict) or 415 (Unsupported Media Type) status codes are suggested

Michael Kropat put together a set of decision charts that helps determine the best status code for each situation. See the following for 4xx status codes:

400 Bad Request is the status code to return when the form of the client request is not as the API expects.401 Unauthorized is the status code to return when the client provides no credentials or invalid credentials.403 Forbidden is the status code to return when a client has valid credentials but not enough privileges to perform an action on a resource.

"The basic principle behind REST status code conventions is that a status code must make the client aware of what is going on and what the server expects the client to do next"

You can fulfill this principle by giving answers to the following questions:Is there a problem or not?If there is a problem, on which side is it? On the client or on the server side?If there is a problem, what should the client do?

Now, assume your client attempts to access a resource that it MUST NOT access at all, for example, because it belongs to another user. What status code should your API return? Should it return a 403 or a 401 status code?You may be tempted to return a 403 status code anyway. But, actually, you can't suggest any missing permission because that client has no way to access that resource. So, the 403 status code gives no actual helpful information. You may think that returning a 401 status code makes sense in this case. After all, the resource belongs to another user, so the request should come from a different user.However, since that resource shouldn't be reached by the current client, the best option is to hide it.

Let's explore a different case now. Assume, for example, that your client sends a request to modify a document and provides a valid access token to the API. However, that token doesn't include or imply any permission or scope that allows the client to perform the desired action.In this case, your API should respond with a 403 Forbidden status code. With this status code, your API tells the client that the credentials it provided (e.g., the access token) are valid, but it needs appropriate privileges to perform the requested action.

The difference is what the server expects the client to do next.

Send a 302 to your login-page

Checks are usually done in this order: 404 if resource is public and does not exist or 3xx redirection OTHERWISE: 401 if not logged-in or session expired 403 if user does not have permission to access resource (file, json, ...) 404 if resource does not exist or not willing to reveal anything, or 3xx redirection

+----------------------- | RESOURCE EXISTS ? (if private it is often checked AFTER auth check) +----------------------- | | NO | v YES v +----------------------- 404 | IS LOGGED-IN ? (authenticated, aka user session) or +----------------------- 401 | | 403 NO | | YES 3xx v v 401 +----------------------- (404 no reveal) | CAN ACCESS RESOURCE ? (permission, authorized, ...) or +----------------------- redirect | | to login NO | | YES | | v v 403 OK 200, redirect, ... (or 404: no reveal) (or 404: resource does not exist if private) (or 3xx: redirection)

The job of this function is to return a { status, headers, body } object representing the response, where status is an HTTP status code: 2xx — successful response (default is 200) 3xx — redirection (should be accompanied by a location header) 4xx — client error 5xx — server error

All browers handle 302 incorrectly. Chrome 30, IE10. It became the de facto incorrect implementation; that cannot be changed because so many web-sites issue mistakenly issue 302. In fact ASP.net MVC incorrectly issues 302, depending on the fact that browsers handle it incorrectly.

Yeah, so I believe what we want is.. If an action has no templates defined at all, AND it has no respond_to { ... } block, then it should do a 204 If an action has certain templates defined, AND it has no respond_to { ... } block, then it should do a 406 for formats with no templates If an action has a respond_to { ... } block, then it should do a 406 for formats not in the list

“What other framework has integrated support for 786 TRY IT NOW ?”

I understand that GitHub uses "Not Found" where it means "Forbidden" in some circumstances to prevent inadvertently reveling the existence of a private repository. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users. --GitHub This is a fairly common practice around the web, indeed it is defined: The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. --6.5.4. 404 Not Found, RFC 7231 HTTP/1.1 Semantics and Content (emphasis mine)