◆Error Codes Wiki

HTTP PATCH Semantics — Partial Update Request Errors and Best Practices

Informational2xx success

Overview

Fix HTTP PATCH method errors including incorrect Content-Type, idempotency issues, and JSON Merge Patch vs JSON Patch format confusion.

Key Details

  • 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

Common Causes

  • 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

Steps

  1. 1Choose the right format: JSON Merge Patch for simple field updates, JSON Patch for complex operations (move, test, arrays)
  2. 2Set the correct Content-Type: application/merge-patch+json for Merge Patch, application/json-patch+json for JSON Patch
  3. 3Return the updated resource in the response body with 200 OK, or 204 No Content if not returning the body
  4. 4Implement proper merge logic: only update fields present in the patch, preserve fields not mentioned
  5. 5Handle concurrent patches with ETags: require If-Match header and return 412 Precondition Failed on conflict

Tags

patchpartial-updatejson-merge-patchjson-patchrest-api

More in 2xx Success

http-200-okHTTP 200 OK — What It Means & How to Fix It
Informational
http-201-createdHTTP 201 Created — What It Means & How to Fix It
Informational
http-202-acceptedHTTP 202 Accepted — What It Means & How to Fix It
Informational
http-203-non-authoritative-informationHTTP 203 Non-Authoritative Information — What It Means & How to Fix It
Informational
http-204-no-contentHTTP 204 No Content — What It Means & How to Fix It
Informational
http-205-reset-contentHTTP 205 Reset Content — What It Means & How to Fix It
Informational

Frequently Asked Questions

Use PATCH for partial updates (changing a few fields). Use PUT for full replacement (sending the complete resource). PUT is idempotent; PATCH may not be.