412 Precondition Failed

Description

The 412 Precondition Failed status code indicates that one or more conditions given in the request header fields evaluated to false when tested on the server. This status code allows the client to place preconditions on the current resource state to prevent the request from being applied if the resource state has changed since the client's last request.

This status code is commonly used when: - A client uses conditional headers like If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-Since - Optimistic concurrency control is implemented to prevent lost updates - A client wants to ensure a resource hasn't changed before modifying it - A client wants to avoid overwriting changes made by other clients

The 412 Precondition Failed status is particularly valuable in collaborative environments where multiple clients might be modifying the same resources.

Syntax

The server responds with a 412 Precondition Failed status:

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
ETag: "current-etag-value"
Content-Length: [length in bytes]

{
  "error": "Precondition Failed",
  "message": "The precondition on the request evaluated to false"
}

Examples

ETag Conditional Update Example

A client attempts to update a resource only if it hasn't changed since the client last retrieved it:

Client Request:

PUT /api/documents/123 HTTP/1.1
Host: docs.example.com
If-Match: "a7f8d2e4c6b9"
Content-Type: application/json
Content-Length: 253

{
  "title": "Updated Document Title",
  "content": "This is the updated content of the document.",
  "author": "Jane Smith"
}

Server Response (when document has been modified):

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
ETag: "e1f2a3b4c5d6"
Content-Length: 215

{
  "error": "Precondition Failed",
  "message": "The document has been modified since you last retrieved it",
  "current_version": "e1f2a3b4c5d6",
  "your_version": "a7f8d2e4c6b9",
  "suggestion": "Retrieve the current version and merge your changes"
}

If-Unmodified-Since Example

A client attempts to update a resource only if it hasn't been modified since a specific time:

Client Request:

PUT /api/articles/456 HTTP/1.1
Host: cms.example.org
If-Unmodified-Since: Wed, 15 Jun 2023 12:30:45 GMT
Content-Type: application/json
Content-Length: 487

{
  "title": "Updated Article Title",
  "content": "This is the updated content of the article.",
  "tags": ["example", "updated", "content"]
}

Server Response (when article has been modified):

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
Last-Modified: Thu, 15 Jun 2023 14:45:22 GMT
Content-Length: 198

{
  "error": "Precondition Failed",
  "message": "The article has been modified since the specified date",
  "last_modified": "2023-06-15T14:45:22Z",
  "your_date": "2023-06-15T12:30:45Z"
}

Multiple Preconditions Example

A client uses multiple preconditions in a request:

Client Request:

DELETE /api/projects/789 HTTP/1.1
Host: api.example.com
If-Match: "b8c9d0e1f2a3"
If-Unmodified-Since: Thu, 15 Jun 2023 09:15:30 GMT
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response (when preconditions fail):

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
ETag: "g4h5i6j7k8l9"
Last-Modified: Thu, 15 Jun 2023 10:20:15 GMT
Content-Length: 243

{
  "error": "Precondition Failed",
  "message": "One or more preconditions failed",
  "details": {
    "etag": {
      "expected": "b8c9d0e1f2a3",
      "actual": "g4h5i6j7k8l9"
    },
    "last_modified": {
      "expected": "2023-06-15T09:15:30Z",
      "actual": "2023-06-15T10:20:15Z"
    }
  }
}

Summary

The 412 Precondition Failed status code is a powerful tool for implementing optimistic concurrency control and preventing data conflicts in web applications and APIs. By allowing clients to specify conditions that must be met before a request is processed, it helps maintain data integrity in collaborative environments where multiple clients might be modifying the same resources. This status code is particularly valuable for PUT, PATCH, and DELETE operations where overwriting changes made by others could lead to data loss or inconsistency.