I am thinking 412 (Precondition Failed) but there may be a better standard?
Status 422 seems most appropiate based on the spec.
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.
They state that malformed xml is an example of bad syntax (calling for a 400). A malformed query string seems analogous to this, so 400 doesn't seem appropriate for a well-formed query-string which is missing a param.
Note: Since the above RFC is about WebDAV there can be a misunderstanding that 422 and some others are only to be used in the context of WebDAV and using them outside of it is "nonstandard". But this only means these status codes were introduced in the context of this RFC. Indeed the wording of these definitions is carefully chosen not to be specific to WebDAV.
I'm not sure there's a set standard, but I would have used 400 Bad Request, which the latest HTTP spec (from 2014) documents as follows:
6.5.1. 400 Bad Request The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
400 Bad Request
is meant to indicate protocol-level problems, not semantic errors. If we're going to hijack HTTP status codes to indicate application-level (rather than protocol-level) errors, why not go all the way and just use 412
?
The WCF API in .NET handles missing parameters by returning an HTTP 404
"Endpoint Not Found" error, when using the webHttpBinding.
The 404 Not Found
can make sense if you consider your web service method name together with its parameter signature. That is, if you expose a web service method LoginUser(string, string)
and you request LoginUser(string)
, the latter is not found.
Basically this would mean that the web service method you are calling, together with the parameter signature you specified, cannot be found.
10.4.5 404 Not Found The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.
The 400 Bad Request
, as Gert suggested, remains a valid response code, but I think it is normally used to indicate lower-level problems. It could easily be interpreted as a malformed HTTP request, maybe missing or invalid HTTP headers, or similar.
10.4.1 400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
You can send a 400 Bad Request code. It's one of the more general-purpose 4xx status codes, so you can use it to mean what you intend: the client is sending a request that's missing information/parameters that your application requires in order to process it correctly.
I Usually go for 422 (Unprocessable entity) if something in the required parameters didn't match what the API endpoint required (like a too short password) but for a missing parameter i would go for 406 (Unacceptable).
Accept-Language: de
, indicating it will only accept responses in German, but the only versions of the requested document that your server has available are in English or French.) Using it to indicate a missing parameter in the request is incorrect, per the definition in spec.
In one of our API project we decide to set a 409 Status to some request, when we can't full fill it at 100% because of missing parameter.
HTTP Status Code "409 Conflict" was for us a good try because it's definition require to include enough information for the user to recognize the source of the conflict.
Reference: w3.org/Protocols/
So among other response like 400 or 404 we chose 409 to enforce the need for looking over some notes in the request helpful to set up a new and right request.
Any way our case it was particular because we need to send out some data eve if the request was not completely correct, and we need to enforce the client to look at the message and understand what was wrong in the request.
In general if we have only some missing parameter we go for a 400 and an array of missing parameter. But when we need to send some more information, like a particular case message and we want to be more sure the client will take care of it we send a 409
For those interested, Spring MVC (3.x at least) returns a 400 in this case, which seems wrong to me.
I tested several Google URLs (accounts.google.com) and removed required parameters, and they generally return a 404 in this case.
I would copy Google.
It could be argued that a 404 Not Found
should be used since the resource specified could not be found.
I often use a 403 Forbidden error. The reasoning is that the request was understood, but I'm not going to do as asked (because things are wrong). The response entity explains what is wrong, so if the response is an HTML page, the error messages are in the page. If it's a JSON or XML response, the error information is in there.
From rfc2616:
10.4.4 403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
Authorization will not help
, so Twitter should not send this for invalid OAuth credentials.
401 Unauthorized
instead. However, you can understand why they don't if you look at the MDN docs' descriptions of these two codes, which are very similar.
Success story sharing
400
is more appropriate.