Skip to main content
apiguide.dev

Prefer Header

Lets the client request optional, non-critical handling behaviors from the server.

Header TypeRequest Header
SpecificationStandard RFC compliant
Associated CodesHTTP 200,HTTP 202

What is the Prefer header?

The Prefer request header, defined in RFC 7240, lets a client indicate preferences for how a request is processed. Preferences are optional hints: the server may honor or ignore them without changing the outcome’s validity.

API Usage & Best Practices

  • Control the response body: return=minimal asks the server to return little or no body, while return=representation asks for the full resource state.
  • Request asynchronous processing: respond-async asks the server to process the request asynchronously, often answered with 202 Accepted; wait= bounds how long the client will wait.
  • Confirm what was applied: When the server acts on a preference, it echoes it back in the Preference-Applied response header.

Examples

POST /v1/orders HTTP/1.1
Host: api.example.com
Prefer: return=minimal, respond-async, wait=10

Associated HTTP Status Codes

HTTP 200 — OK

The request has succeeded. The response payload contains the requested resource representation.

View reference →

HTTP 202 — Accepted

The request has been accepted for processing, but the processing has not been completed.

View reference →

Sponsors

Support the project →