Prefer
The HTTP Prefer request header communicates optional processing preferences to the server, allowing clients to influence response behavior without affecting request semantics.
Usage
The Prefer header enables clients to express preferences about how a server processes a request and constructs a response. Preferences are advisory. A server is free to ignore any or all preferences without causing the request to fail. When a server honors one or more preferences, the Preference-Applied response header confirms which ones were applied.
The header follows an extensible token-based syntax. Multiple preferences appear as a comma-separated list, and each preference accepts optional parameters delimited by semicolons.
Prefer: preference-name; parameter=value
The IANA Preferences Registry maintains the list of registered preference tokens. Non-registered preferences are allowed as long as the server understands them. Unrecognized tokens are silently ignored.
The Prefer header is widely used in RESTful APIs, OData services, and PostgREST to control response verbosity, asynchronous processing, and error handling behavior.
Directives
respond-async
The respond-async preference asks the server to process
the operation asynchronously instead of waiting for completion.
A server honoring this preference typically returns 202
Accepted with a Location header pointing to a
status monitoring endpoint.
Prefer: respond-async
return=minimal
The return=minimal preference requests a minimal response body
after a successful operation. For POST or PUT
requests creating or updating a resource, the server omits the
resource representation and returns only status and headers. This
reduces bandwidth when the client does not need the full response.
Prefer: return=minimal
return=representation
The return=representation preference asks the server to
include the full current state of the resource in the response
body after processing. This eliminates the need for a follow-up
GET request to retrieve the updated resource.
Prefer: return=representation
handling=lenient
The handling=lenient preference asks the server to be tolerant
of minor errors, unknown properties, or edge cases during request
processing. The server processes what is valid and ignores
unrecognized elements rather than rejecting the entire request.
Prefer: handling=lenient
handling=strict
The handling=strict preference asks the server to apply strict
validation. The server rejects requests containing unknown or
invalid elements instead of silently ignoring them.
Prefer: handling=strict
wait
The wait preference specifies the maximum number of seconds the
client is willing to wait for a response. If the server cannot
complete processing within the specified duration, a partial or
interim response is returned.
Prefer: wait=30
Example
A client creating a resource through a POST request prefers an asynchronous response and is willing to wait up to 10 seconds before receiving an interim status.
Prefer: respond-async, wait=10
A client updating a resource requests the full representation in the response body, avoiding a separate GET request to fetch the updated state.
Prefer: return=representation
A client sending a batch operation to an API asks for lenient handling so the server processes valid entries and skips malformed ones rather than rejecting the entire batch.
Prefer: handling=lenient
Takeaway
The Prefer request header lets clients express optional processing preferences like asynchronous handling, response verbosity, and validation strictness. Servers confirm honored preferences through the Preference-Applied response header.