Repository: mdn/content
Pull request #37659: feat(http): Add Prefer, Preferrence-Applied headers
Author: login: alivedise
Labels: name: Content:HTTP
description: HTTP docs
name: size/m
description: [PR only] 51-500 LoC changed
Created: 2025-01-15T17:13:36Z | Merged: 2025-03-28T04:47:15Z

<!-- 🙌 Thanks for contributing to MDN Web Docs. Adding details below will help us to merge your PR faster. -->

### Description
This PR adds two pages for Prefer related headers which are specified in RFC7240 and [IETF header registry](https://www.iana.org/assignments/http-fields/http-fields.xhtml).

### Motivation

I am not sure why they(`Prefer`, `Preferrence-Applied`) are not listed on MDN. Is it because the browser has nothing to do with the header? But I see `Expect` also in the MDN header list and I think it is not a browser-oriented header, either.

### Additional details

* https://datatracker.ietf.org/doc/html/rfc8144
* https://datatracker.ietf.org/doc/html/rfc7240

### Related issues and pull requests
None AFAIK.


Diff:
diff --git a/files/en-us/web/http/reference/headers/index.md b/files/en-us/web/http/reference/headers/index.md
index d274b0fa04263a2..a3c8d6e3f6333f0 100644
--- a/files/en-us/web/http/reference/headers/index.md
+++ b/files/en-us/web/http/reference/headers/index.md
@@ -167,6 +167,17 @@ For more information, refer to the [CORS documentation](/en-US/docs/Web/HTTP/Gui
 - {{HTTPHeader("Content-Location")}}
   - : Indicates an alternate location for the returned data.
 
+## Preferences
+
+Preferences can be sent by clients in requests to indicate optional behaviors for requests and responses.
+The server response may indicate if a preference is applied, in cases where it would otherwise be ambiguous for the client.
+Browsers have no native handling for sending preferences via these headers; they are used in custom, implementation-specific clients.
+
+- {{HTTPHeader("Prefer")}}
+  - : Indicates preferences for specific server behaviors during request processing. For example, it can request minimal response content (`return=minimal`) or asynchronous processing (`respond-async`). The server processes the request normally if the header is unsupported.
+- {{HTTPHeader("Preference-Applied")}}
+  - : Informs the client which preferences specified in the `Prefer` header were applied by the server. It is a response-only header providing transparency about preference handling.
+
 ## Proxies
 
 - {{HTTPHeader("Forwarded")}}
diff --git a/files/en-us/web/http/reference/headers/prefer/index.md b/files/en-us/web/http/reference/headers/prefer/index.md
new file mode 100644
index 000000000000000..97da6046025580d
--- /dev/null
+++ b/files/en-us/web/http/reference/headers/prefer/index.md
@@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> Servers should silently ignore preferences that they do not support, as though the header were not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+    For example, the server might respond with {{httpstatus("202", "202 (Accepted)")}} response indicated that the request has been accepted, along with the {{httpheader("Location")}} header that has a URL that the client can use to monitor the state of the processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The time within which the client expects the server to provide a response, from the point at which the request was received.
+    If the `respond-async` preference is also provided, the server should respond asynchronously if processing the request will exceed the wait time.
+    Otherwise, the server should consider that the client will timeout after the `wait` time (response behavior depends on server implementation).
+- `handling=lenient`
+  - : The client wishes the server to apply lenient validation and error handling to the processing of the request.
+- `handling=strict`
+  - : The client wishes the server to apply strict validation and error handling to the processing of the request.
+- Custom preference
+  - : Vendors or applications may define their own preferences to suit specific needs.
+    For example, `Prefer: timezone=America/Los_Angeles`.
+
+## Examples
+
+### Requesting minimal response
+
+The following request asks for a minimal response.
+This is typically a headers-only response (as opposed to `return=representation` where a representation is included in the response body):
+
+```http
+POST /resource HTTP/1.1
+Host: example.com
+Content-Type: application/json
+Prefer: return=minimal
+
+{"id":123, "name": "abc"}
+```
+
+The server responds with a {{httpstatus("201")}}, but does not include any response body.
+The {{httpheader("Location")}} header contains a URL with the location of the newly-created resource.
+There's no need to include a `Preference-Applied` header because the absence of a response body is readily apparent:
+
+```http
+HTTP/1.1 201 Created
+Location: /resource?id=123
+```
+
+### Requesting asynchronous processing
+
+This example requests the server start an async processing task:
+
+```http
+POST /process HTTP/1.1
+Host: example.com
+Prefer: respond-async
+
+{
+  "task": "check-broken-links"
+}
+```
+
+The server responds with a {{httpstatus("202", "202 (Accepted)")}} response indicated the request has been accepted and has not yet completed executing asynchronously.
+A `Location` header points to a status monitor that represents the state of the processing:
+
+```http
+HTTP/1.1 202 Accepted
+Location: http://example.com/tasks/123/status
+```
+
+### Providing multiple preferences
+
+The following request includes two preferences; `timezone=Jupiter/Red_Spot` indicating a time zone preference for the client, and `handling=strict` for strict validation:
+
+```http
+GET /events HTTP/1.1
+Host: example.com
+Prefer: handling=strict, timezone=Jupiter/Red_Spot
+```
+
+In this implementation, an invalid time zone will throw an error:
+
+```http
+HTTP/1.1 400 Bad Request
+```
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- {{HTTPHeader("Preference-Applied")}}
+- [Prefer header](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358871) on docs.oasis-open.org
+- [Prefer header](https://docs.postgrest.org/en/v12/references/api/preferences.html) on docs.postgrest.org
diff --git a/files/en-us/web/http/reference/headers/preference-applied/index.md b/files/en-us/web/http/reference/headers/preference-applied/index.md
new file mode 100644
index 000000000000000..0d4f775bdd04191
--- /dev/null
+++ b/files/en-us/web/http/reference/headers/preference-applied/index.md
@@ -0,0 +1,75 @@
+---
+title: Preference-Applied
+slug: Web/HTTP/Reference/Headers/Preference-Applied
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-3
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Preference-Applied`** header informs the client about which preferences from the {{httpheader("Prefer")}} request header were applied by the server.
+
+The server indicates if a preference is applied to a response if it would otherwise be ambiguous for the client.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Response header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+    <tr>
+      <th scope="row">
+        {{Glossary("CORS-safelisted response header")}}
+      </th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Preference-Applied: <preference>
+```
+
+## Examples
+
+### Server applies timezone preferences
+
+The following request indicates that the client prefers events to be represented in a certain time zone:
+
+```http
+GET /events HTTP/1.1
+Host: example.com
+Prefer: timezone=America/Los_Angeles
+```
+
+The server supports the preference and sends back the content with a `Preference-Applied` header:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+Preference-Applied: timezone=America/Los_Angeles
+
+[
+  {"t":"2023-10-18T05:37:59.611-07:00"},
+  {"t":"2023-10-18T07:37:59.611-07:00"},
+  {"t":"2023-10-18T09:37:59.611-07:00"}
+]
+```
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- {{HTTPHeader("Prefer")}}
+- [Prefer header](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358871) on docs.oasis-open.org
+- [Prefer header](https://docs.postgrest.org/en/v12/references/api/preferences.html) on docs.postgrest.org


Reviews:
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-01-31T06:15:14Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-01-31T06:16:44Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-01-31T06:20:26Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-01-31T06:21:30Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-14T09:20:41Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-18T16:31:52Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-18T16:32:07Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-18T16:32:13Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T00:12:50Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T00:18:15Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T00:26:59Z
user: login: hamishwillee
body: Looks good - thanks so much for following up on this. Just a few suggestions
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-21T00:28:53Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-24T12:55:24Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-24T22:04:37Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-24T22:08:09Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-25T13:18:24Z
user: login: bsmth
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-25T13:19:35Z
user: login: bsmth
body: I think we're ready to go here minus the last thread about client timeouts. I'll leave my +1 for now in the meantime ✅ 
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-25T13:22:16Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-27T22:45:51Z
user: login: hamishwillee
body: Thanks @alivedise and @bsmth - I think this is good now. Merging!
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-27T22:46:58Z

Review comments:
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: Preference-Applied
+slug: Web/HTTP/Headers/Preference-Applied
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-3
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Preference-Applied`** header informs the client about which preferences from the `Prefer` request header were applied by the server.
path: files/en-us/web/http/headers/preference-applied/index.md
user: login: hamishwillee
body: ```suggestion
The HTTP **`Preference-Applied`** header informs the client about which preferences from the {{httpheader("Prefer"}} request header were applied by the server.
```
created_at: 2025-01-31T06:15:14Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: Preference-Applied
+slug: Web/HTTP/Headers/Preference-Applied
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-3
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Preference-Applied`** header informs the client about which preferences from the `Prefer` request header were applied by the server.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Response header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+    <tr>
+      <th scope="row">
+        {{Glossary("CORS-safelisted response header")}}
+      </th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Preference-Applied: <preference>
+```
+
+## Examples
+
+### Server acknowledges a minimal response preference
+
+```http
+HTTP/1.1 200 OK
+Preference-Applied: return=minimal
+```
+
+### Server acknowledges an asynchronous processing preference
+
+```http
+HTTP/1.1 202 Accepted
+Preference-Applied: respond-async
+```
path: files/en-us/web/http/headers/preference-applied/index.md
user: login: hamishwillee
body: Can you please update the examples to show the request that caused this response (with appropriate words). You could do the same for `prefer`. The whole thing is a little abstract otherwise. 
created_at: 2025-01-31T06:16:44Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: Prefer
+slug: Web/HTTP/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> The `Prefer` header is often used in custom client-server implementations. Ensure both client and server support this header before relying on it in production.
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences. Instead, the server processes the request as if the header was not present.
path: files/en-us/web/http/headers/prefer/index.md
user: login: hamishwillee
body: This is good. My concern here is that this has no specific browser integration. That might be worth spelling out (it is implied but not said). Words like "(browsers have no specific handling for these header: they are processed custom client code) or similar

Further, if this is used in a few protocols it might be worth listing a few, such as  "Open Data (OData) protocol"


created_at: 2025-01-31T06:20:25Z
author_association: COLLABORATOR
diff_hunk: @@ -167,6 +167,13 @@ For more information, refer to the [CORS documentation](/en-US/docs/Web/HTTP/COR
 - {{HTTPHeader("Content-Location")}}
   - : Indicates an alternate location for the returned data.
 
+## Preference
+
path: files/en-us/web/http/headers/index.md
user: login: hamishwillee
body: Again, might we worth a prefix line custom client-server implementations: they have no specific handling in the browser.
created_at: 2025-01-31T06:21:30Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: Preference-Applied
+slug: Web/HTTP/Reference/Headers/Preference-Applied
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-3
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Preference-Applied`** header informs the client about which preferences from the `Prefer` request header were applied by the server.
path: files/en-us/web/http/reference/headers/preference-applied/index.md
user: login: bsmth
body: ```suggestion
The HTTP **`Preference-Applied`** header informs the client about which preferences from the {{httpheader("Prefer"}} request header were applied by the server.
```
created_at: 2025-03-14T09:20:41Z
author_association: MEMBER
diff_hunk: @@ -167,6 +167,13 @@ For more information, refer to the [CORS documentation](/en-US/docs/Web/HTTP/COR
 - {{HTTPHeader("Content-Location")}}
   - : Indicates an alternate location for the returned data.
 
+## Preference
+
path: files/en-us/web/http/headers/index.md
user: login: bsmth
body: added some details here https://github.com/mdn/content/pull/37659/commits/2470cc7cb29a13a97139500b42500ac0d8d9b53a
created_at: 2025-03-18T16:31:52Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,74 @@
+---
+title: Prefer
+slug: Web/HTTP/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> The `Prefer` header is often used in custom client-server implementations. Ensure both client and server support this header before relying on it in production.
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences. Instead, the server processes the request as if the header was not present.
path: files/en-us/web/http/headers/prefer/index.md
user: login: bsmth
body: Added something here: https://github.com/mdn/content/pull/37659/commits/2470cc7cb29a13a97139500b42500ac0d8d9b53a
created_at: 2025-03-18T16:32:07Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,61 @@
+---
+title: Preference-Applied
+slug: Web/HTTP/Headers/Preference-Applied
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-3
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Preference-Applied`** header informs the client about which preferences from the `Prefer` request header were applied by the server.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Response header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+    <tr>
+      <th scope="row">
+        {{Glossary("CORS-safelisted response header")}}
+      </th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Preference-Applied: <preference>
+```
+
+## Examples
+
+### Server acknowledges a minimal response preference
+
+```http
+HTTP/1.1 200 OK
+Preference-Applied: return=minimal
+```
+
+### Server acknowledges an asynchronous processing preference
+
+```http
+HTTP/1.1 202 Accepted
+Preference-Applied: respond-async
+```
path: files/en-us/web/http/headers/preference-applied/index.md
user: login: bsmth
body: See https://github.com/mdn/content/pull/37659/commits/2470cc7cb29a13a97139500b42500ac0d8d9b53a
created_at: 2025-03-18T16:32:13Z
author_association: MEMBER
diff_hunk: @@ -10,8 +10,11 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
 The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
 
 > [!NOTE]
-> The `Prefer` header is often used in custom client-server implementations. Ensure both client and server support this header before relying on it in production.
-> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences. Instead, the server processes the request as if the header was not present.
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: hamishwillee
body: 1. Servers do whatever they like, so this is "should do" not "does do".
2. Perhaps simpler to say

```suggestion
> Servers should silently ignore preferences that they do not support, as though the header were not present.
```
created_at: 2025-03-21T00:12:50Z
author_association: COLLABORATOR
diff_hunk: @@ -167,6 +167,17 @@ For more information, refer to the [CORS documentation](/en-US/docs/Web/HTTP/Gui
 - {{HTTPHeader("Content-Location")}}
   - : Indicates an alternate location for the returned data.
 
+## Preferences
+
+Preferences can be sent by clients in requests to indicate optional behaviors for requests and responses.
+The server may indicate if a preference is applied to a response if it would otherwise be ambiguous for the client.
path: files/en-us/web/http/reference/headers/index.md
user: login: hamishwillee
body: ```suggestion
The server may indicate if a preference is applied to a response if it would otherwise be ambiguous for the client.
```
```suggestion
The server response may indicate if a preference is applied, in cases where it would otherwise be ambiguous for the client.
```
created_at: 2025-03-21T00:18:15Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The maximum time the client expects it will take for the server to process the request once it's been received.
+    For example, if `respond-async` preference is also provided, the client requests that the service respond asynchronously after the specified length of time.
+    Otherwise, a server may interpret the wait time as a request to timeout after the specified period of time.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: hamishwillee
body: For example doesn't feel quite right here. 
- I think with `respond-async` this means "time in which I want my HTTP response" not "time that the whole thing will take.
- I think for sync responses we're saying "this is a timeout", but what happens then - the server still responds with something presumably.

If so, then in either case it is the time until a response is expected. So something like ...

```suggestion
  - : The time within which the client expects the server to provide a response, from the point at which the request was received.
    If `respond-async` preference is also provided this is the time at which the initial response is provided (not completion of processing).
    For synchronous processing, a server may should timeout and respond if it unable to process the request in this timeframe.
```
created_at: 2025-03-21T00:26:59Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The maximum time the client expects it will take for the server to process the request once it's been received.
+    For example, if `respond-async` preference is also provided, the client requests that the service respond asynchronously after the specified length of time.
+    Otherwise, a server may interpret the wait time as a request to timeout after the specified period of time.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: bsmth
body: I think the original is a little closer: https://datatracker.ietf.org/doc/html/rfc7240#section-4.3

>The "wait" preference can be used to establish an upper bound on the
   length of time, in seconds, the client expects it will take the
   server to process the request once it has been received.  In the case
   that generating a response will take longer than the time specified,
   the server, or proxy, can choose to utilize an asynchronous
   processing model by returning -- for example -- a 202 (Accepted)
   response.
   
This is probably the most relevant section:

>For example, a server receiving the following request might choose to
>   respond asynchronously if processing the request will take longer
>   than 10 seconds:
>
>     POST /collection HTTP/1.1
>     Host: example.org
>     Content-Type: text/plain
>     Prefer: respond-async, wait=10
>
>     {Data}

I interpret this as:

* `Prefer: respond-async` <- client can technically handle async responses
* `Prefer: wait=10` <- client will wait 10 seconds for a response, otherwise timeout
* `Prefer: respond-async, wait=10` <- respond asynchronously if processing the request will take longer than 10 seconds

So we could modify your suggestion to be:


```
The time within which the client expects the server to provide a response, from the point at which the request was received.
If the `respond-async` preference is also provided, the server should respond asynchronously if processing the request will exceed the wait time.
Otherwise, a server may consider `wait` the time it will take to send a synchronous response before the client times out.
```

created_at: 2025-03-24T12:55:23Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The maximum time the client expects it will take for the server to process the request once it's been received.
+    For example, if `respond-async` preference is also provided, the client requests that the service respond asynchronously after the specified length of time.
+    Otherwise, a server may interpret the wait time as a request to timeout after the specified period of time.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: hamishwillee
body: That's helpful. So FMI if a client times out, what does it do with the response? What should  server send if it knows the client is timing out. That might affect what we write. See what I mean below with Xxxxx.

```suggestion
  - : The time within which the client expects the server to provide a response, from the point at which the request was received.
    If the `respond-async` preference is also provided, the server should respond asynchronously if processing the request will exceed the wait time.
    Otherwise, the server should consider that the client will timeout after the `wait` time and Xxxxx
```
created_at: 2025-03-24T22:04:37Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,130 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> Servers should silently ignore preferences that they do not support, as though the header were not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: hamishwillee
body: Should we outline anything here or leave it to the example, I tend to like a little more

```suggestion
  - : The client prefers asynchronous processing.
    For example, the server might respond with {{httpstatus("202", "202 (Accepted)")}} response indicated that the request has been accepted, along with the {{httpheader("Location")}} header that has a URL that the client can use to monitor the state of the processing.
```
created_at: 2025-03-24T22:08:08Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The maximum time the client expects it will take for the server to process the request once it's been received.
+    For example, if `respond-async` preference is also provided, the client requests that the service respond asynchronously after the specified length of time.
+    Otherwise, a server may interpret the wait time as a request to timeout after the specified period of time.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: bsmth
body: This is great. Only problem is the "and Xxx" is not clearly speccd, so this depends on server implementation. Probably 408 https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/408 but the spec doesn't even go that far / make any assumptions what happens here. I think we're good with everything up to " and Xxxxx".
created_at: 2025-03-25T13:18:24Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,130 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> Servers should silently ignore preferences that they do not support, as though the header were not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: bsmth
body: Yeah this is good 👍🏻 
created_at: 2025-03-25T13:19:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,131 @@
+---
+title: Prefer
+slug: Web/HTTP/Reference/Headers/Prefer
+page-type: http-header
+spec-urls: https://www.rfc-editor.org/rfc/rfc7240#section-2
+---
+
+{{HTTPSidebar}}
+
+The HTTP **`Prefer`** header allows clients to indicate preferences for specific server behaviors during request processing.
+
+> [!NOTE]
+> Browsers have no handling for the `Prefer` and {{HTTPHeader("Preference-Applied")}} headers: they are used in custom, implementation-specific clients.
+> Ensure both client and server support this header before relying on it in production.
+>
+> The `Prefer` header does not cause the server to return an error if it does not support or apply the specified preferences.
+> Instead, the server processes the request as if the header was not present.
+
+<table class="properties">
+  <tbody>
+    <tr>
+      <th scope="row">Header type</th>
+      <td>
+        {{Glossary("Request header")}}
+      </td>
+    </tr>
+    <tr>
+      <th scope="row">{{Glossary("Forbidden header name")}}</th>
+      <td>No</td>
+    </tr>
+  </tbody>
+</table>
+
+## Syntax
+
+```http
+Prefer: <preference>
+```
+
+## Directives
+
+- `respond-async`
+  - : The client prefers asynchronous processing.
+- `return=minimal`
+  - : Requests that the server return minimal content (a headers-only response).
+- `return=representation`
+  - : Requests a full resource representation in the response.
+- `wait=<seconds>`
+  - : The maximum time the client expects it will take for the server to process the request once it's been received.
+    For example, if `respond-async` preference is also provided, the client requests that the service respond asynchronously after the specified length of time.
+    Otherwise, a server may interpret the wait time as a request to timeout after the specified period of time.
path: files/en-us/web/http/reference/headers/prefer/index.md
user: login: hamishwillee
body: It's not ideal, but if that is the reality. I've decided to add a note that the behaviour is server dependent as this is useful.

```suggestion
  - : The time within which the client expects the server to provide a response, from the point at which the request was received.
    If the `respond-async` preference is also provided, the server should respond asynchronously if processing the request will exceed the wait time.
    Otherwise, the server should consider that the client will timeout after the `wait` time (response behavior depends on server implementation).
```
created_at: 2025-03-27T22:45:51Z
author_association: COLLABORATOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-01-16T09:57:31Z
body: <!-- build_hash: ae1fa5674735c318fe47d0d4d8c0ae7c date: 2025-03-27T23:08:27.601Z -->

<b>Preview URLs</b>

- [`/en-US/docs/Web/HTTP/Reference/Headers/Prefer`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Prefer)
- [`/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied)
- [`/en-US/docs/Web/HTTP/Reference/Headers`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers)


<details><summary><b>Flaws</b> (6)</summary>

URL: [`/en-US/docs/Web/HTTP/Reference/Headers`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers)
Title: `HTTP headers`
Flaw count: 4

- **macros**:
  - `Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Accept-Signature`
  - `Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Signature`
  - `Can't resolve /en-US/docs/Web/HTTP/Reference/Headers/Signed-Headers`
- **unknown**:
  - `No generic content config found`

---

URL: [`/en-US/docs/Web/HTTP/Reference/Headers/Prefer`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Prefer)
Title: `Prefer`
Flaw count: 1

- **macros**:
  - `Macro produces link /en-US/docs/Glossary/Forbidden_header_name which is a redirect`

---

URL: [`/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied)
Title: `Preference-Applied`
Flaw count: 1

- **macros**:
  - `Macro produces link /en-US/docs/Glossary/Forbidden_header_name which is a redirect`

</details>


<details><summary><b>External URLs</b> (4)</summary>

URL: [`/en-US/docs/Web/HTTP/Reference/Headers/Prefer`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Prefer)
Title: `Prefer`

  - <https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html> (1 time) (Note! This may be a new URL 👀)
  - <https://docs.postgrest.org/en/v12/references/api/preferences.html> (1 time) (Note! This may be a new URL 👀)

---
URL: [`/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied`](https://pr37659.review.mdn.allizom.net/en-US/docs/Web/HTTP/Reference/Headers/Preference-Applied)
Title: `Preference-Applied`

  - <https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html> (1 time) (Note! This may be a new URL 👀)
  - <https://docs.postgrest.org/en/v12/references/api/preferences.html> (1 time) (Note! This may be a new URL 👀)

</details>

*(comment last updated: 2025-03-27 23:08:27)*
author_association: CONTRIBUTOR
user: login: bsmth
created_at: 2025-01-16T10:04:01Z
body: Thanks for suggesting, typically the criteria for inclusion is whether there's current browser support, but there are some exceptions. In the HTTP section, some mechanisms and headers are described that are basically transparent to the browser. For those it's mostly decided case-by-case and whether they're used in other systems / web technologies.

For these two headers, they look important for the Open Data (OData) protocol (https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-odata/b4768cbf-13d5-40df-bfa3-7d43ef73e882, https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358871) and [PGRest](https://docs.postgrest.org/en/v12/references/api/preferences.html), among others, so I'm +1 on adding these as the footprint is small for the additions 👍🏻 

author_association: MEMBER
user: login: github-actions[bot]
created_at: 2025-03-13T12:50:38Z
body: This pull request has merge conflicts that must be resolved before it can be merged.
author_association: CONTRIBUTOR
user: login: hamishwillee
created_at: 2025-03-14T00:03:00Z
body: @alivedise Are you planning on responding to the comments?

@bsmth I presume this is waiting on @alivedise and not me? Assuming we are waiting on the author, should one of us just do the requested updates?
author_association: COLLABORATOR
user: login: bsmth
created_at: 2025-03-14T09:19:45Z
body: > I presume this is waiting on @alivedise and not me? Assuming we are waiting on the author, should one of us just do the requested updates?

Sure, I can take over the edits in the meantime

author_association: MEMBER
user: login: hamishwillee
created_at: 2025-03-16T23:48:15Z
body: > > I presume this is waiting on @alivedise and not me? Assuming we are waiting on the author, should one of us just do the requested updates?
> 
> Sure, I can take over the edits in the meantime

@bsmth Thank you! Ping me when you need a final review.

author_association: COLLABORATOR