HTTP PATCH Semantics — Partial Update Request Errors and Best Practices

Fix HTTP PATCH method errors including incorrect Content-Type, idempotency issues, and JSON Merge Patch vs JSON Patch format confusion. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: HTTP PATCH applies partial modifications to a resource, unlike PUT which replaces the entire resource. Two standard patch formats: JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902). JSON Merge Patch uses application/merge-patch+json content type and merges the patch into the resource. JSON Patch uses application/json-patch+json and applies an ordered list of operations (add, remove, replace, move, copy, test). PATCH is not guaranteed to be idempotent — applying the same patch twice may produce different results. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Using application/json content type instead of the specific patch content type. Sending a full resource as PATCH body (should use PUT for full replacement). JSON Merge Patch unable to set a field to null (null means delete in merge patch). Server treating PATCH as PUT and replacing the entire resource instead of merging. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Choose the right format: JSON Merge Patch for simple field updates, JSON Patch for complex operations (move, test, arrays). Set the correct Content-Type: application/merge-patch+json for Merge Patch, application/json-patch+json for JSON Patch. Return the updated resource in the response body with 200 OK, or 204 No Content if not returning the body. Implement proper merge logic: only update fields present in the patch, preserve fields not mentioned. Handle concurrent patches with ETags: require If-Match header and return 412 Precondition Failed on conflict. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.