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

Question

I have several pages designed to be called with AJAX - I have them return an abnormal status code if they can't be displayed, and my javascript will show an error box accordingly.

For example, if the user is not authenticated or their session has timed out and they try to call one of the AJAX pages, it will return 401 Unathorized.

I also have some return 500 Internal Server Error if something really odd happens server-side.

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

I had a look at the wikipedia article on HTTP status codes, but the closest one I could find to the code I'm looking for was this:

422 Unprocessable Entity
The request was well-formed but was unable to be followed due to semantic errors.

Edit: The above code is WebDAV specific and therefore unlikely to be appropriate in this case

Can anyone think of an appropriate code to return?

Answer 1

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.

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 resonse 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.

Answer 2

I don't know about the RFC writers' intentions, but the status code I have seen used in the wild for that case is 400 Bad Request.