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?

Fleck

See as well (if that's not a duplicate even): HTTP status code for bad data – Incomprehensible

@JulianReschke I think 4918 could do with some errata, firstly to specify that it does update 2616, and secondly to clarify that the new HTTP status codes are not all WebDAV specific. – Munmro

@Alnitak: (1) It does not update RFC 2616 because it doesn't have to. There's a status code registry, and that's what being used: <greenbytes.de/tech/webdav/rfc4918.html#rfc.section.21.4> (2) In general, HTTP status codes are supposed to be generic; that's why there's a registry. – Dower

Duplicate. The debate rages on... – Constitutive

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.

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.

Incomprehensible

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. In case of missing parameters, the syntax will still be correct, which makes me to believe 400 is a bad choice. Correct me if I am wrong anywhere :) – Porbeagle

@Thrustmaster: You're not wrong, but a bit narrow minded. Only because it could be that, does not mean it can't mean the other. Especially for the x00 codes that is true. Added some more info. – Incomprehensible

I might be a bit narrow minded, hehe. I am still not convinced . I guess I will read the RFC entirely before I comment any further. Thanks for the answer, upvoted :) – Porbeagle

Yeah read the RFC. And relax your mind a bit probably ;) The most important part is that you have a 4xx code, in case the client does not understand it, it will treat it as 400. So probably it's best to start with 400 and a useful entity you attach (response body) and if you come to a better conclusion choose a more specific code. The most important part is that you tell the user what he/she did wrong so a 2xx request status can be achieved for future requests for the intended action. – Incomprehensible

-1: 404 is a very inappropriate choice. It means that the endpoint was not found, that is, it does not exist, which is plain false in this case. Also: 404 Not Found is a subset of 400 Bad Request: where did you learn that? It is totally false. – Emersonemery

@LucaFagioli: All 4xx are a subset of 400, that's just the basics of the status code meanings, you find it since the first HTTP RFCs. For the concrete 404 I'm with you that your mileage may vary whether you find it fitting best. As in my previous comment, go with 400 then if you don't have a preference/fit in the 401-499 (including) range. If you have, take that one. And always take what is best for the semantic of your application of/on the server. – Incomprehensible

@Incomprehensible please find me any official RFC link that supports your statement about 4xx being a subset of 400. – Emersonemery

@LucaFagioli: Just take the first one and look for the classes. You even find it in the section semantics of the document IIRC. – Incomprehensible

@Incomprehensible You were not able to find it, I found it for you, RFC 9110. 4xx is the class. 400 is a status code, like 401 or 404. This answer is totally wrong. – Emersonemery

@LucaFagioli: I've noticed your concerns and made this visible, thanks for your inspiration. – Incomprehensible

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.

Almeda

400 is, IMO, a bad choice. Check my comment below hakre's answer. Do tell me if I am wrong in any way :) – Porbeagle

I did (probably not up there in the comment), 404 :) – Porbeagle

Sometimes I wonder if the standard http status codes are adequate. – Capricorn

@Porbeagle since you are asking, yes, you are wrong. 404 means simply not found, and it's probably the most popular error code of the entire Internet since it was born. Here are other logically equivalent expressions of "not found" that might help you understand where and when using correctly: Absent, Missing, Nonexistent, Unavailable and Not present. 404 is very well known even by the general public, in a way that even advertisers know how to use it appropriately. – Emersonemery

A note of confirmation from Wikipedia: The website hosting server will typically generate a "404 Not Found" web page when a user attempts to follow a broken or dead link; hence the 404 error is one of the most recognizable errors encountered on the World Wide Web. – Emersonemery

Thanks for the English lession. And because "you fail to understand .. 404 is okay", the server deems when any of the resource is absent, missing, non-existent, unavailable or not present. If a server uses "Effective URI" (query params) to locate a resource (as in OP's case), it might very well say 404. – Porbeagle

You've been off-track from the premises of the discussion. No one disputed whether 404 is the "most recognizable errors since internet.." or if it's simply "not found". We are talking about how OP's specific case extends into 404 realm. And if the case being made conflicts with the RFCs at all. This is what both Hakre (Last line of their answer) and I have been saying all along: 404 is not a bad option at all. If you any RFC text that talks about this conflict, let me know. Or, if you'd like to exhibit your command over the language by listing out the synonyms -- please keep it to yourself. – Porbeagle

@Porbeagle What you fail to understand is that query parameters are not part of the URL. That's why you think that 404 "is OK after all", because "after all, it's a wrong URL". That's completely wrong. Query parameters are not part of the URL. It's very easy man... – Emersonemery

They are indeed a part of HTTP URI. Here's the RFC. Ctrl+F this page to search for "Effective URI". – Porbeagle

Man, at a certain point it's not my responsibility to teach you how to read an RFC, or to teach you how to design a proper API. Feel free to return 404. And thanks for the shortcut, but it did not work, since there are no occurrences of "Effective URI". – Emersonemery

I literally pointed out and linked the RFC that says query parameters are a part of HTTP URI (and how a server could use the "Effective URI", deem for the resource to be missing and 404 out the request). You ask for RFCs but choose to not answer pointed questions when one is being linked, or acknowledge when you're plain wrong. I can take take the horse to the water, but cant make it drink. And with that I'll stop dignifying trolls like you with a response. You're not worth my time. – Porbeagle

It's because you just wanted to be right since the begin. You're one of those people and I get obviously annoyed. By the way, the square brackets mean that they are an optional part of the URI. I am with you that the RFC may be open to interpretation, but if you stop and think logically, 404 is just a bad choice. The resource is there, it has been found, but it has been used incorrectly. It's a "bad request". With "not found" you'll make the API consumer waste time into checking if the endpoint is correct or not. Respect your API consumer man. – Emersonemery

Answer 3

422 is a regular HTTP status code; and it is used outside WebDAV. Contrary to what others say, there's no problem with that; HTTP has a status code registry for a reason.

See http://www.iana.org/assignments/http-status-codes

Dower

Sure you can use 478 as well, it's your choice, you're not bound to any RFC. However I would not suggest to re-use a WEBDAV specific code for this question. And technically you don't need to rely to IANA as well, as long as it's something 4xx it's clear for any HTTP useragent, see the HTTP specs. It's just a question what you want. – Incomprehensible

Well, 422 is a code in the IANA status code registry, defined in an IETF Standards Track RFC. 478 is not. – Dower

So what? It will take years until 478 will be used and when that's the case and you've established commons around it, IETF will reflect it. Especially if the client is your own controlled AJAX client, there is not much to care about outside of your domain. It's even probably more wise to use an unused status code than to re-use something of which IANA already states that it is used for a specific purpose, a WEBDAV connection. – Incomprehensible

Using a currently unassigned code is a bad idea. Somebody might specify it with different semantics, and one day you'll find that HTTP libraries add special handling for it. So don't. And no, IANA doesn't state that 422 is specific to WebDAV. All the registry page says is where the status code is defined. I'm done here; if you don't trust me on this I recommend that you ask over on the IETF HTTP mailing list. – Dower

Answer 4

Read this carefully:

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

422 is a WebDAV-specific thing, and I haven't seen it used for anything else.

400, even though not intended for this particular purpose, seems to be a common choice.

404 is also a viable choice if your API is RESTful or similar (using the path part of the URI to indicate search parameters)

Congenial

422 is not WebDAV-specific, and it is used in other contexts. – Dower

Answer 5

Description as quoted against 400

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

(Emphasis mine)

That speaks of malformed syntax, which is not the case when the browser sends a request to the server. Its just the case of missing parameters (while there's no malformed syntax).

I would suggest stick with 404 :)

(Experts correct me if I am wrong anywhere :) )

Porbeagle

See trac.tools.ietf.org/wg/httpbis/trac/ticket/303; the revision of RFC 2616 will clarify that "malformed Syntax" is just one of many potential reasons. – Dower

I know that this is really old now, but I just want to say that 404 usually means that the page that you are requesting isn't found. For example, if you want to make a call to page.com/api, but you misspell it and request page.com/aip, page.com/aip would return with 404. Correct me if I am wrong, though... – Sheree

Answer 6

In your scenario, it seems like the request itself is incomplete or malformed, so the 400 Bad Request status code would be more appropriate.

A 404 status code is intended to indicate that the requested resource could not be found on the server. However, in the case of an error with the query parameters, the resource being requested does exist, but the request was malformed or incomplete.

Returning a 404 status code in this situation could lead to confusion for the client, who may assume that the requested resource does not exist when it actually does. This could result in wasted time and effort as the client tries to locate a resource that cannot be found due to a misunderstanding of the server's response.

By returning a 400 Bad Request status code instead, the server communicates to the client that there was an error with the request itself, rather than the existence of the requested resource. This helps to ensure that the client understands the nature of the error and can take appropriate action to correct it.

Emersonemery

datatracker.ietf.org/doc/html/…. I'd argue that the server is unable to find anything against the effective URI (including parameters) and hence 404, as opposed to a 400 malformed systax (bad HTTP encoding). There is no misleading going on, as long as the HTTP response body describes the reason accurately. – Porbeagle

What you very wildly assuming by referring to "bad HTTP encoding" is handled at a lower level of the protocol, so your endpoint will never have to deal with it. Back to syntax now: syntax means - generally speaking - grammar. By providing the wrong parameters you are violating the expected grammar of your endpoint. Hence 400. Regarding 404, a resource is pointed by a URI path, and query parameters are not part of it. Do you need a proof? You will be able to access to a resource even with wrong or unexpected parameters. 404 means that the API consumer is pointing to the wrong path. – Emersonemery

Again, as far as 400 v/s 404 goes, I am not saying 400 is wrong -- just that 404 is okay too. And that the standards, in their strict reading, aren't against using 404 in this case. And I just downvoted your answer because your second line is in fact misleading. – Porbeagle

404 means not found. In this case the endpoint is obviously found, otherwise it wouldn't be possible to handle the parameters request. I fail to understand how you can say it's ok too. – Emersonemery