What the PATCH method is used for

The PATCH method is used to apply partial modifications to an existing resource. Instead of replacing the whole representation, the request supplies changes for only the fields you want to update, leaving the rest untouched. In contrast, PUT replaces the entire representation and is idempotent MDN: PATCH MDN: PUT.

When to use PATCH

• Update a single field, such as a user’s status or display name.
• Change a small subset of fields without sending the full resource.
• Avoid overwriting unspecified fields that must remain unchanged.

MDN defines PATCH as “applies partial modifications,” and highlights that PUT is a full replacement. PATCH may not be idempotent; PUT is idempotent MDN: PATCH MDN: PUT.

How PATCH works: requests, headers, and responses

• Request body: PATCH requests include a body describing the changes to apply MDN: PATCH.
• Content type and support: Servers can advertise PATCH support via Allow or Access-Control-Allow-Methods, and indicate accepted patch document media types using the Accept-Patch header. Clients should set an appropriate Content-Type so the server can interpret the patch document MDN: PATCH.
• Success codes: A successful PATCH can return standard 2xx codes. For example, many APIs return 200 OK (with the updated representation) or 204 No Content. MDN shows a 204 example and includes an ETag so clients can make conditional requests later MDN: PATCH.
• Safety and cache: PATCH is not safe and not idempotent. It is only cacheable when responses include explicit freshness information and a matching Content-Location header MDN: HTTP methods.

Idempotency, retries, and conflicts

PATCH is not inherently idempotent, so identical retries can lead to different outcomes if the operation has accumulating effects MDN: PATCH. If you need safe retries in your application design, consider using idempotency keys and make your patch operations set explicit values rather than perform increments.

Concurrent edits can conflict. Many servers include an ETag with successful responses so clients can issue conditional requests later and avoid overwriting intervening changes MDN: PATCH. If your API is evolving, ensure you document how PATCH behaves across versions and how clients should migrate API versioning.

Common mistakes and how to avoid them

• Using PATCH for full replacements. If you intend to replace the entire representation, use PUT instead MDN: PUT.
• Omitting Content-Type. Servers need to know which patch document media type you’re sending; servers may advertise accepted types via Accept-Patch MDN: PATCH.
• Blind automatic retries. PATCH is not inherently idempotent; design explicit retry rules and consider idempotency keys for operations that must be safely retried MDN: PATCH.
• Ignoring method support. Check Allow or CORS methods headers to confirm PATCH is supported before sending updates MDN: PATCH.

Quick checklist for using PATCH safely

• Confirm the endpoint supports PATCH (Allow or Accept-Patch headers)
• Set Content-Type to the patch document’s media type
• Send only the fields you intend to change
• Plan retries: use idempotency keys for operations that may be retried
• Use ETag-based conditional requests to prevent overwriting concurrent changes

FAQ

Does PATCH return 200 or 204?

Either is valid. Success can be indicated by standard 2xx status codes; many APIs choose 200 OK (with a body) or 204 No Content. MDN shows a 204 example and returns an ETag for future conditional updates MDN: PATCH.

Is PATCH cacheable?

Not by default. PATCH is only cacheable when responses include explicit freshness information and a matching Content-Location header MDN: HTTP methods.