509

I am thinking 412 (Precondition Failed) but there may be a better standard?

Daniel Vassallo
  • 337,827
  • 72
  • 505
  • 443
EA.
  • 5,370
  • 2
  • 18
  • 13

10 Answers10

508

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.

David Ongaro
  • 3,568
  • 1
  • 24
  • 36
Kelvin
  • 20,119
  • 3
  • 60
  • 68
  • 4
    IMO I would use this for when the value in the query string was incorrect, not when there was an extra value or a missing value. ie. Expecting an e-mail and its value is '123123' – Derek Litz Jan 25 '13 at 17:23
  • @DerekLitz what status would you use for extra/missing value? – Kelvin Jan 25 '13 at 21:51
  • 2
    I tend to think of a GET and POST parameters as the method signature of the URL path, so 404 makes sense to me. In a RESTful API meant for public consumption it is prudent to return the missing/extra parameters. In the context of a URL the query string parameters are usually important for identifying a resource and extra or missing parameters represent a resource that does not exist, without any assumptions. Of course, there are trade offs with robustness by being explicit, and optional parameters make a resource potentially just as vulnerable to silent error. Then there's usability... – Derek Litz Jan 26 '13 at 15:07
  • @DerekLitz "Query params as method signature" is an interesting interpretation, which has some merit. I tend to disagree though. I come from the Ruby on Rails world, and some "params" are actually part of the resource path (e.g. the "1" in POST /comments/1) - these I'd consider to be the required params that identify the resource; while the qstring contains optional params. Of course we can't be dogmatic about it since there's no standard; just use what you think is best. – Kelvin Feb 19 '13 at 17:28
  • @DerekLitz OTOH, a 404 would make perfect sense if you're doing pure REST, and the query string is only ever provided by the content at another resource. So resource A has the url (including qstring) pointing to resource B, and the client should never be generating the qstring on their own. – Kelvin Feb 19 '13 at 17:31
  • 17
    The spec referenced is for WebDAV, and is not the HTTP standard spec. – David V May 26 '14 at 19:11
  • 3
    @DavidV You're correct that it's for WebDAV, but there doesn't seem to be a better option for core HTTP. [This blog](http://www.bennadel.com/blog/2434-http-status-codes-for-invalid-data-400-vs-422.htm) mentions popular APIs using 422. – Kelvin Jun 02 '14 at 19:09
  • 1
    @Kelvin Thanks for pointing out that blog post. It is helpful to see that Twitter, for example, is using 422. I think the answer might be better if you clarify that the spec is WebDAV in the first line. When I first read your answer I thought you meant the HTTP standard spec until I followed the link. – David V Jul 16 '14 at 13:44
  • 1
    @DavidV Status codes, and methods are not limited to the specification they are defined in. That's why we now have global registries http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml – Darrel Miller Oct 02 '14 at 21:45
  • 3
    This is worth a read: https://www.bennadel.com/blog/2434-http-status-codes-for-invalid-data-400-vs-422.htm I would not use 422 for missing param either. I think `400` is more appropriate. – Zelphir Kaltstahl Apr 10 '17 at 12:49
  • 1
    Take a look at https://stackoverflow.com/a/20215807/10245 - it seems the reason for preferring 422 over 400 has gone away. – Tim Abell Aug 06 '18 at 08:40
  • In addition 422 refers to the request entity, so not applicable to url parameters. – OrangeDog Sep 17 '19 at 14:57
  • @StopHarmingMonica parameters can be in the body for POST. Query string vs in the body seems like an artificial distinction in this case. – Kelvin Nov 15 '19 at 16:52
  • @jenson-button-event care to elaborate? – Kelvin Nov 15 '19 at 16:53
  • @Kelvin it might seem like that to you, but not to the HTTP protocol. That's why people are telling you you're wrong. – OrangeDog Nov 15 '19 at 16:54
  • Isn't this out-dated according to the following? https://softwareengineering.stackexchange.com/questions/329229/should-i-return-an-http-400-bad-request-status-if-a-parameter-is-syntactically#:~:text=The%20400%20(Bad%20Request)%20status,%2C%20or%20deceptive%20request%20routing). – Mohammed Noureldin Mar 21 '21 at 14:00
  • 1
    @DavidV This answer is correct. Your comment that `422` is for WebDAV, while technically / historically correct, is moot. `422` has surfaced as the de-facto standard status code for validation errors and is the correct status code to use in the scenarios described by the OP. It would be good if the HTTP people would change the text to reflect that really, `422` is used across the board and not limited to WebDAV. It was selected because the HTTP people just sorta forgot about validation errors. ... ¯\_(ツ)_/¯ – Stijn de Witt Aug 24 '22 at 08:18
  • @ZelphirKaltstahl *"I think `400` is more appropriate"*. No. `400` is specifically for parse errors. Think of it this way, if you try to parse JSON or XML etc, `400` is the status code you would return in your `catch` block when a parse error happened. `422` is the status code you would return when the parse went successful, but your validation code returns errors because some data in the request was invalid. – Stijn de Witt Aug 24 '22 at 08:20
  • @StijndeWitt Missing parameter **is** a parse error. Missing parameter could make not finding proper method (if methods are different by their parameters - then 404 would be appropriate) or pass *null* when value is required, which means no null allowed. – Sylwester Zarębski Feb 16 '23 at 14:51
235

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

Community
  • 1
  • 1
Gert Grenander
  • 16,866
  • 6
  • 40
  • 43
  • 74
    `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`? – Matt Zukowski Jul 30 '10 at 16:05
  • 50
    Google's OAuth 1.0 implementation agrees with this answer. A 400 response is given when POST parameters are missing or unsupported: http://code.google.com/apis/accounts/docs/OAuth_ref.html – Tom Oct 29 '11 at 00:21
  • 2
    @matt-zukowski: "412: The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server." from [RFC2616](http://www.ietf.org/rfc/rfc2616.txt) - If it's a POST, the parameters are in the request body and not the request-header-fields. Technically, the GET method sends it's parameters in the request-headers but I'd rather have some consistency instead ? – toong Mar 01 '12 at 14:30
  • 7
    @MattZukowski 400 is an application level status code. If you look at the rewording in the draft version of RFC 7231 you will see that. Unfortunately, the wording in the latest version is not so clear because the author of the latest changes also invented 422. – Darrel Miller Oct 02 '14 at 21:44
  • 10
    @DarrelMiller is right ([direct link](https://tools.ietf.org/html/rfc7231#section-6.5.1)): *"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)."* Depending on semantics and extensibility expectations (will it one day be possible to issue a request without the parameter?) then only 400 and 404 seem appropriate in standard HTTP. Else, invent a new code for your API, but don't overload semantics. – tne Jun 03 '15 at 11:34
  • This seems the only acceptable answer. WebDAV is no HTTP standard, so it can't be used. – Davatar Apr 05 '18 at 02:05
  • 1
    @MattZukowski 400 is for any client error. In particular any condition covered by any 4xx code is also valid to use 400, though you'd lose some utility. – OrangeDog Sep 17 '19 at 14:43
  • Unless the relevant spec says MUST when encountering that condition. – OrangeDog Sep 17 '19 at 14:59
  • This is what Google recommends in https://cloud.google.com/apis/design/errors - `400 INVALID_ARGUMENT Request field x.y.z is xxx, expected one of [yyy, zzz].` – Ben May 08 '20 at 13:58
  • I don't know why status codes standards don't follow a type of hierarchy where 400 is the root code. i.e. all 4xx codes are specific versions of 400. Then, when in doubt, we can always use a "base code". The meaning, if not specific, is at least clear to the cilent. – cammil Nov 29 '20 at 10:30
  • Personally I like sending "bad request" because that's what it is, a bad request. It's semantically meaningful to a layperson. – redcartel Jan 08 '22 at 20:00
  • @Davatar The HTTP people just messed up by not including status codes for validation errors. `422` is the de-facto standard and has grown beyond WebDAV a long time ago. `400` has a very specific meaning. If you tell the client to send JSON, because you tell them you accept `application/json`, then `400` is for when the body fails to parse as JSON. If it does parse succesfully as JSON, `400` is out. – Stijn de Witt Aug 24 '22 at 08:25
36

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.

Community
  • 1
  • 1
Daniel Vassallo
  • 337,827
  • 72
  • 505
  • 443
  • This is what CherryPy does by default. – Derek Litz Jan 25 '13 at 17:20
  • What about when handling a post request where you're accepting a model and part of the model is missing? In that case you don't get a 404. Instead you get a model that's not valid if I'm not mistaken and you have to decide what to do now. – Shane Courtrille Sep 25 '15 at 22:45
  • 2
    This interpretation seems like a stretch, and expresses an RPC rather than a REST pov. The URI is the identifier, and it exists and has been found. What is sent in the body is not part of the resource identifier. 422 is more appropriate. – Jonah Sep 29 '16 at 17:27
  • 404 is the right answer, just go edit some urls on the web to find the consensus! – jenson-button-event Nov 13 '19 at 13:16
  • For GET requests, `404` definitely makes sense. Consider e.g `http://example.com/articles?id=345`. If you change `345` to a non-existing ID, you are requesting an article that does not exist and `404` would be the best answer. However, there is a trend that parameters that are identifying for the resource should be in the `path` part of the URL and (optional) paging/search etc parameters should be in the querystring. So better would be e.g. `http://example.com/article/345?comments=on` where `comments` would be optional and no `404` would result from leaving it out. – Stijn de Witt Aug 24 '22 at 08:30
  • *"I think it is normally used to indicate lower-level problems. "* Yes, it is related to the `Accept` and `Content-Type` headers. Basically, if you say you are sending `application/json` but your message does not parse as JSON, `400` is suitable. But if the parse succeeds, `400` is not appropriate and `422` becomes the better code to use. – Stijn de Witt Aug 24 '22 at 08:33
  • 404 is one of the *worst possible choices*. It specifically means the resource was not found - as in a server side page or file doesn't exist at that path - not a parameter was not included in the request - two completely different errors with very different root causes. Using 404 is worse than a vague error - it's misdirection. Do you know how mad I would be if I spent hours trying to find out why my endpoint didn't exist only to find out I was only missing a required parameter? Mashing completely unrelated errors together under the same code defeats the entire purpose of having error codes. – dallin Sep 01 '22 at 03:55
20

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.

BoltClock
  • 700,868
  • 160
  • 1,392
  • 1,356
7

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

Elad Meidar
  • 774
  • 6
  • 11
  • 13
    Well, 406 Unacceptable is used with Accept header (if server can't send response the client will understand). "The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request." . I'm stuck with 422 as there is no "right" choice with current specification :-/ – JakubKnejzlik Oct 14 '14 at 16:21
  • 1
    Using 406 for this is wrong. A 406 code doesn't mean that the *request* was not acceptable; it means that you can't satisfy the request because the responses you're able to serve are ones that the *client* would find unacceptable, based on the Accept headers it sent in the request. (For instance, the request included `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. – Mark Amery Jan 04 '20 at 17:04
  • *"I'm stuck with 422"* Yes, you hit the nail on the head. The world is stuck with `422` because it's simply the least bad of the very limited set of options we were given. Most other status codes have very specific technical meanings and diluting those meanings by using them for other purposes as well is much worse than using `422` for non-WebDAV protocols. So yes, `422` because there is nothing better. – Stijn de Witt Aug 24 '22 at 08:44
5

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

gabrielem
  • 560
  • 5
  • 13
  • 8
    This is plain wrong. 409 is for concurrency issues as @MaximeGélinas points out OR situations where a resource is already present and duplicates are not allowed. – gimlichael Jan 12 '19 at 18:36
  • 1
    Per spec, *"The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource."*. Using it for a missing parameter is just wrong; that's a totally different sort of error. – Mark Amery Jan 04 '20 at 16:59
  • @gimlichael and Mark Avery are correct. `409` is wrong. Basically, when a client gets a `409` response, it should show a message to the user saying 'oops, someone else edited that record in the mean time' and showing e.g. a diff screen. It is very specifically for concurrency/locking issues. The famous example of you reading a record, some other user also reading that record, that other user saving the record and then you trying to save that record, The changes made by the other user would be lost. In that case, `409 Conflict` would be the right response. – Stijn de Witt Aug 24 '22 at 08:48
4

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.

Relefant
  • 928
  • 10
  • 10
  • 26
    Because Google does it does not automatically mean Google does it right! – rve Sep 27 '13 at 08:36
  • 6
    I agree, not necessarily 'right' but sometimes what's right and what's sensible are two different things. Anyhow.. up to the reader :) – Relefant Oct 24 '13 at 15:08
  • Some Google APIs return a 400, e.g. https://github.com/google/google-api-nodejs-client/issues/404 – Dennis May 12 '16 at 19:06
  • which is wrong (and why spring mvc is not jax-rs compliant) – jenson-button-event Nov 13 '19 at 13:17
  • 404 makes sense when the parameter is contributing to identifying the resource. E.g `http://example.com/user?id=345`. Some parameters however don't identify the resource. E.g `http://example.com/user/345?showFriends=true`. There is a trend in the industry to put those parameters that take part in identifying the resource in the path part of the URL (as in the second example) and reserve the querystring for optional parameters that only say how to show the resource etc. I would recommend you follow this trend in future apis and place identifying parametes in the path part. – Stijn de Witt Aug 24 '22 at 09:08
3

It could be argued that a 404 Not Found should be used since the resource specified could not be found.

Luca
  • 9,259
  • 5
  • 46
  • 59
Ray
  • 55
  • 1
  • 3
    This is the default behavior of Java JAX-RS when a query parameter cannot be converted to the proper datatype. I don't agree with it though. The resource WAS found: query parameters are for filtering the resource and one of the filters was supplied with an unacceptable value. I think this matches 422 Unprocessable Entity closest, and 400 Bad Request second closest. – Ryan Apr 02 '14 at 18:09
  • its the default behaviour of jax-rs because its the right behaviour! – jenson-button-event Nov 13 '19 at 13:17
  • 1
    Using a 404 is reasonable when the query string parameter is meant to identify a resource, a value was given, but that value doesn't correspond to a resource that exists - for instance, if you're requesting http://example.com/show-user-profile?user_id=123 and user 123 doesn't exist. But that's not what this question asked about; it was about the scenario where a required parameter is omitted entirely. I don't see how that corresponds to a specified resource not being found. – Mark Amery Jan 04 '20 at 17:08
0

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.

Community
  • 1
  • 1
cdeszaq
  • 30,869
  • 25
  • 117
  • 173
  • 4
    Sounds good initially, although I'd naturally associate this with authentication or permission based errors. Also, the spec hints towards this where it says "if the server does not wish to make this information available to the client". Also that 404 might be a better option. I'd head towards a 404 or 400 than a 403. – tonyhb Dec 02 '12 at 20:37
  • 29
    This is a terrible idea, even if technically sound. 403 is universally used for auth failure responses, and you will confuse the hell out of your clients if you try to use this to indicate parameter errors. For example Twitter does this — 403 is used both when you provide invalid OAuth credentials, and when there is something semantically wrong with your request — and it is a constant source of confusion for API clients. – Matt Zukowski Oct 06 '14 at 17:58
  • 1
    @MattZukowski well that's just wrong. The spec says `Authorization will not help`, so Twitter should not send this for invalid OAuth credentials. – torvin Feb 26 '18 at 01:02
  • @torvin Twitter should be sending a `401 Unauthorized` instead. However, you can understand why they don't if you look at [the MDN docs' descriptions](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) of these two codes, which are very similar. – Agi Hammerthief Jul 26 '18 at 13:39
  • You should describe the reason of failure in your response. If you prefer not to do it, just use 404. – Francisco Costa Nov 11 '20 at 18:18
-3

Just go to the browser settings > Shields > Auto-redirect AMP pages Disable it and try again ...

Talal khawaja
  • 15
  • 2