HTTP status code

The HTTP 428 status code stands for "Precondition Required". It is a client error response indicating that the server requires the client to meet certain preconditions before processing the request. This status code is typically used in situations where the server wants to ensure that certain conditions are met, such as checking whether a resource has been modified or whether certain headers are included in the request.

When is HTTP 428 Used?

The 428 Precondition Required status code is returned when the server expects the client to include specific conditions or preconditions as part of the request. For example, this might involve conditions related to resource modification, such as checking if the resource has changed since a certain timestamp.
It is often used to enforce idempotency or ensure that certain actions are performed only if specific conditions are met, typically in web applications or RESTful APIs.

Common Causes of HTTP 428 Errors

Missing or failed preconditions: The server requires specific conditions to be met before processing a request, such as verifying that a resource has not changed or has been locked.
Optimistic concurrency control: The server may require a condition like an If-Match or If-None-Match header, often used in concurrency control, to ensure that the resource has not been modified by another process since the client last fetched it.
Client attempting an unsafe action: The client may be attempting an action that could lead to unintended consequences without ensuring certain conditions, such as modifying a resource without confirming it hasn't been changed by another request in the meantime.

Example Scenarios

A client tries to update a resource but does not include an If-Match header with the correct version of the resource, causing the server to return a 428 error to indicate that the update cannot proceed without verifying that the resource hasn't changed.
A client attempts to delete a resource without checking that the resource has been locked or hasn't been modified by other users or processes, triggering the server to return a 428 status code.

Example

Client Request (Missing Precondition)

    
        PUT /users/123 HTTP/1.1
        Host: example.com
        Content-Type: application/json

        {
          "name": "John Doe",
          "email": "johndoe@example.com"
        }

(The client tries to update the user resource, but does not include the required If-Match header to ensure the resource has not been modified.)

Server Response (428 Precondition Required)

    
        HTTP/1.1 428 Precondition Required
        Content-Type: application/json

        {
          "error": "The request requires the 'If-Match' header to verify the resource has not been modified."
        }

Best Practices for Handling HTTP 428

Clearly communicate preconditions: The server should provide clear instructions in the error message, informing the client about which conditions need to be met before the request can be processed (e.g., include an If-Match header).
Use conditional headers: When working with concurrency control in RESTful APIs, ensure that the client uses the appropriate conditional headers, such as If-Match, If-None-Match, or If-Modified-Since, to prevent issues with data consistency.
Prevent unsafe operations: The server can use this status code to prevent unsafe or conflicting operations, such as attempting to modify a resource that has already been changed by another client.
Client awareness: Clients should be aware of the need for certain preconditions before sending requests and ensure they are properly including the required headers or conditions.

Summary

HTTP 428 is used when the server requires preconditions to be met before it can process a request. This typically involves checking for changes to a resource or ensuring that the client is acting on the most up-to-date version of the resource. The client should ensure that all necessary preconditions, such as headers for concurrency control (e.g., If-Match), are included in the request.