73

It is unclear to me when you should and should not return a HTTP 412: Precondition Failed, error for a web service? I am thinking of using it when validating data. For example, if a client POST's XML data and that data is missing a required data element, then responding with a 412 and a description of the error.

Does that align with the spirit of responding with an HTTP 412, or should something else be used (e.g. another http error code or web application exception)?

Elias Zamaria
  • 96,623
  • 33
  • 114
  • 148
TERACytE
  • 7,553
  • 13
  • 75
  • 111
  • Treat all 4YY errors as client errors. Treat 412 Precondition Failed as 400 Bad Request. That is, the client (GUI / script) has sent the wrong input to an API. – Manohar Reddy Poreddy Apr 09 '21 at 19:10
  • HTTP error 412 is used when you are using row versions or timestamps to avoid concurrency issues. If you sent the web service a record and include the row version in the header, the web service can compare that row version to the current row version. If the values don't match, you reject the request to update with a 412 error. – Quark Soup Aug 17 '21 at 11:17

3 Answers3

90

If you look at RFC 2616 you'll see a number of request headers that can be used to apply conditions to a request:

If-Match
If-Modified-Since
If-None-Match
If-Range
If-Unmodified-Since

These headers contain 'preconditions', allowing the client to tell the server to only complete the request if certain conditions are met. For example, you use a PUT request to update the state of a resource, but you only want the PUT to be actioned if the resource has not been modified by someone else since your most recent GET.

The response status code 412 (Precondition Failed) is typically used when these preconditions fail.

Your example sounds like an invalid request (i.e. the client has submitted data that is invalid because of missing values). A status code of 400 (Bad Request) is more appropriate here IMO.

joelittlejohn
  • 11,665
  • 2
  • 41
  • 54
  • 412 is also used when the row version (optimistic concurrency) fails. If you send a request with a row version that doesn't match the row version that the server has, you should fail with 412. – Quark Soup Aug 17 '21 at 11:15
  • 1
    @Quark Soup that is what If-Match is for. Although it is not the only way to do it. – Joachim Lous Apr 25 '23 at 08:11
26

412 is reserved for cases where the request is conditional, and the condition isn't met.

For your use case, 422 Unprocessable Entity is a good match.

Julian Reschke
  • 40,156
  • 8
  • 95
  • 98
  • 10
    It's worth mentioning that status code `422` is not part of RFC 2616. It's part of an extension to HTTP 1.1 for WebDAV. – joelittlejohn Mar 20 '11 at 18:58
  • 3
    joelittlejohn: why is that a problem? Status codes are an extension point in RFC 2616, and this is a very useful extension. – Julian Reschke Jun 18 '11 at 07:28
  • 6
    I didn't mean to imply that it's a problem, only that it's worth mentioning :) – joelittlejohn Jun 29 '11 at 23:40
  • I like this as well. It clearly distinguishes requests that are rejected for business validation reasons from those rejected due to transient conditions or software bugs. These three classes of error need to be very differently. – dsmith Dec 17 '18 at 17:20
12

Your best bet would be to avoid 412. In practice most web services that I've used send a 400 code (Bad Request). A lot of frameworks have built-in support for 400 too and your clients will appreciate a more common error code. Often times, especially with REST interfaces, a simple "message" or "error" element is returned with a description.

Matt Bishop
  • 1,010
  • 7
  • 18
  • 4
    Clients are supposed to treat any unknown 4xx code as 400 anyway. – Julian Reschke May 13 '14 at 11:58
  • 1
    @JoelFan 404 wouldn't be an unknown code. That one should probably be handled while any 400-499 codes not explicitly handled should be treated as a generic 400. – BamaPookie Jun 29 '16 at 19:48
  • 1
    @BamaPookie - 404 is resource not found. 412 is precondition failed, which seems vague. Is that the reason why we prefer to treat all the vague responses as 400 ? Or is it something else ? – MasterJoe Feb 15 '17 at 07:12