What Http Status Code Is Supposed to Be Used to Tell the Client the Session Has Timed Out

What http status code is supposed to be used to tell the client the session has timed out?

Best I can suggest is a HTTP 401 status code with a WWW-Authenticate header.

The problem with 403 requests is the the RFC 2616 states "Authorization will not help and the request SHOULD NOT be repeated." (i.e. doesn't matter if you are authenticated or not, you are not going to get access to that resource, ever).

The problem with 401 requests is it states they "MUST include a WWW-Authenticate header field". As someone has noted it doesn't appear to be in violation of the spec to use a custom value in a WWW-Authenticate header.

I can't see any reason in RFC 2617 why an HTTP 401 status combined with a custom WWW-Authenticate header like this wouldn't be okay:

WWW-Authenticate: MyAuthScheme realm="http://example.com"

The oAuth spec actually seems to do just this, as they recommend this (though they have to my mind an odd interpretation of the RFC):

WWW-Authenticate: OAuth realm="http://server.example.com/"

This doesn't appear to be specifically SANCTIONED by the RFC, but I can't actually see that it's forbidden by it (it doesn't seem to conflict with any MUST or MUST NOT, SHOULD or SHOULD NOT condition).

I wish there was a more specific HTTP status code for timeouts and for things like CSRF tokens being invalid so this was clearer.

What is a connection timeout during a http request

I will try to answer it a little bit more informally.

Connection timeout - is a time period within which a connection between a client and a server must be established. Suppose that you navigate your browser (client) to some website (server). What happens is that your browser starts to listen for a response message from that server but this response may never arrive for various reasons (e.g. server is offline). So if there is still no response from the server after X seconds, your browser will 'give up' on waiting, otherwise it might get stuck waiting for eternity.

Request timeout - as in the previous case where client wasn't willing to wait for response from server for too long, server is not willing to keep unused connection alive for too long either. Once the connection between server and client has been established, client must periodically inform server that it is still there by sending information to that server. If client fails to send any information to server in a specified time, server simply drops this connection as it thinks that client is no longer there to communicate with it (why wasting resources meaninglessly).

Time to live (TTL) - is a value specified inside of a packet that is set when the packet is created (usually to 255) that tells how long the packet can be left alive in a network. As this packet goes through the network, it arrives at routers that sit on the path between the packet's origin and its destination. Each time the router resends the packet, it also decrements its TTL value by 1 and if that value drops to 0, instead of resending the packet, router simply drops it as the packet is not supposed to live any longer. This mechanism is used to prevent network from flooding by data as each packet can live inside of it for only limited amount of 'time'.

What are the complete intervals of HTTP Status Codes that might occur in REST API?

An API can return any status code it wishes to. Whether you have to handle it or not is a matter of the contract between your system and the API: ideally, a well-documented API will list all possible status codes it can return, eliminating the guesswork.

In most real-world cases, though, you can assume anything in the 200-299 range "succeeded", and anything else did not. Your distinction between 4xx and 5xx is correct. 3xx's are a little weird, as a 301/302 means you might just need to follow the redirect, and sometimes a 304 Not Modified will still mean the operation succeeded, but it depends on the API's implementation. 1xx's are not expected in a REST API.

Lastly, remember that while each status code has a meaning, they're only as meaningful as the API makes them. I have seen many production APIs that return 200s even for error responses, instead pushing the error status down into the body payload. Take care when generalizing your error handling to still allow the callers to access the original response for edge cases like these.

When to use Request timeout and Gateway timeout

Once your server is acting as a gateway or proxy of an upstream server, you should use 504 to indicate that the connection has timed out. See how this status code is defined:

6.6.5. 504 Gateway Timeout

The 504 (Gateway Timeout) status code indicates that the server,
while acting as a gateway or proxy, did not receive a timely response
from an upstream server it needed to access in order to complete the
request.

The 408 status code has a completed different meaning and indicates that the server would like to shut down an unused connection with the client:

6.5.7. 408 Request Timeout

The 408 (Request Timeout) status code indicates that the server did
not receive a complete request message within the time that it was
prepared to wait. A server SHOULD send the "close" connection option
in the response, since 408 implies that
the server has decided to close the connection rather than continue
waiting. If the client has an outstanding request in transit, the
client MAY repeat that request on a new connection.

Which HTTP status code to use for required parameters not provided?

What status code should I return if one of these pages was called without required parameters? (and therefore can't return any content).

You could pick 404 Not Found:

The server has not found anything matching the Request-URI [assuming your required parameters are part of the URI, i.e. $_GET]. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

(highlight by me)

404 Not Found is a subset of 400 Bad Request which could be taken as well because it's very clear about what this is:

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

This is normally more common with missing/wrong-named post fields, less with get requests.

As Luca Fagioli comments, strictly speaking 404, etc. are not a subset of the 400 code, and correctly speaking is that they fall into the 4xx class that denotes the server things this is a client error.

In that 4xx class, a server should signal whether the error situation is permanent or temporary, which includes to not signal any of it when this makes sense, e.g. it can't be said or would not be of benefit to share. 404 is useful in that case, 400 is useful to signal the client to not repeat the request unchanged. In the 400 case, it is important then for any request method but a HEAD request, to communicate back all the information so that a consumer can verify the request message was received complete by the server and the specifics of "bad" in the request are visible from the response message body (to reduce guesswork).

I can't actually suggest that you pick a WEBDAV response code that does not exist for HTTP clients using hypertext, but you could, it's totally valid, you're the server coder, you can actually take any HTTP response status code you see fit for your HTTP client of which you are the designer as well:

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code means the server
understands the content type of the request entity (hence a
415(Unsupported Media Type) status code is inappropriate), and the
syntax of the request entity is correct (thus a 400 (Bad Request)
status code is inappropriate) but was unable to process the contained
instructions. For example, this error condition may occur if an XML
request body contains well-formed (i.e., syntactically correct), but
semantically erroneous, XML instructions.

IIRC request entity is the request body. So if you're operating with request bodies, it might be appropriate as Julian wrote.

---

You commented:

IMHO, the text for 400 speaks of malformed syntax. I would assume the syntax here relates to the syntax of HTTP string that the client sends across to the server.

That could be, but it can be anything syntactically expressed, the whole request, only some request headers, or a specific request header, the request URI etc.. 400 Is not specifically about "HTTP string syntax", it's infact the general answer to a client error:

The 4xx class of status code is intended for cases in which the client seems to have erred. Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents SHOULD display any included entity to the user.

The important part is here that you must tell the client what went wrong. The status code is just telling that something went wrong (in the 4xx class), but HTTP has not been specifically designed to make a missing query-info part parameter noteable as error condition. By fact, URI only knows that there is a query-info part and not what it means.

If you think 400 is too broad I suggest you pick 404 if the problem is URI related, e.g. $_GET variables.

---

Related Topics