428 Precondition Required

Description

The 428 Precondition Required status code indicates that the server requires the request to be conditional. This status code is designed to prevent the "lost update" problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, unaware that a third party has modified the state on the server, resulting in a conflict.

This status code is commonly used when: - A server wants to enforce optimistic concurrency control - A server requires clients to confirm they're working with the current version of a resource - A server wants to prevent race conditions in concurrent updates - A server requires conditional requests for certain operations to ensure data integrity

The 428 Precondition Required status helps maintain data integrity by requiring clients to include conditional headers like If-Match or If-Unmodified-Since in their requests.

Syntax

The server responds with a 428 Precondition Required status:

HTTP/1.1 428 Precondition Required
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Precondition Required",
  "message": "This request requires a conditional header"
}

Examples

Resource Update Example

A client attempts to update a resource without using a conditional request:

Client Request:

PUT /api/documents/123 HTTP/1.1
Host: docs.example.com
Content-Type: application/json
Content-Length: 253
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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

Server Response:

HTTP/1.1 428 Precondition Required
Content-Type: application/json
ETag: "a7f8d2e4c6b9"
Content-Length: 243

{
  "error": "Precondition Required",
  "message": "This API requires conditional requests for updates",
  "required_header": "If-Match or If-Unmodified-Since",
  "current_etag": "a7f8d2e4c6b9",
  "documentation": "https://docs.example.com/api/conditional-requests"
}

Resource Deletion Example

A client attempts to delete a resource without confirming they have the current version:

Client Request:

DELETE /api/products/456 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response:

HTTP/1.1 428 Precondition Required
Content-Type: application/json
ETag: "b8c9d0e1f2a3"
Last-Modified: Wed, 15 Jun 2023 14:30:22 GMT
Content-Length: 215

{
  "error": "Precondition Required",
  "message": "Deletion requires confirmation that you have the current version",
  "required_header": "If-Match",
  "current_etag": "b8c9d0e1f2a3"
}

Concurrent Editing Example

A client attempts to edit a document that might be edited by others:

Client Request:

PATCH /api/collaborative-document/789 HTTP/1.1
Host: collaboration.example.org
Content-Type: application/json-patch+json
Content-Length: 145
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

[
  { "op": "replace", "path": "/title", "value": "New Document Title" },
  { "op": "add", "path": "/sections/0", "value": { "heading": "Introduction", "content": "New introduction text." } }
]

Server Response:

HTTP/1.1 428 Precondition Required
Content-Type: application/json
ETag: "c0d1e2f3g4h5"
Content-Length: 287

{
  "error": "Precondition Required",
  "message": "This collaborative document requires conditional requests to prevent edit conflicts",
  "instructions": "First GET the current document to obtain its ETag, then include that ETag in an If-Match header with your PATCH request",
  "current_etag": "c0d1e2f3g4h5"
}

Summary

The 428 Precondition Required status code is a valuable tool for enforcing optimistic concurrency control and preventing the "lost update" problem in web applications and APIs. By requiring clients to include conditional headers in their requests, servers can ensure that clients are aware of the current state of resources before modifying them. This helps maintain data integrity in scenarios where multiple clients might be updating the same resources concurrently. The status code was formally defined in RFC 6585 and has become an important part of RESTful API design best practices.