What does the Prefer header actually do?

Prefer lets a client ask the server for optional, non-critical behaviour without making the request fail if the server ignores it. The server is free to apply some, all, or none of the listed preferences. It is a hint, not a command.

What is the difference between return=minimal and return=representation?

return=minimal asks the server to send the smallest useful body, often just a 204 or a Location header after a write. return=representation asks the server to include the full resulting resource in the response body, saving a follow-up GET.

How do I know if my preference was applied?

A compliant server echoes the preferences it honoured in the Preference-Applied response header. If a token you sent is absent there, the server chose not to apply it. Preferences are never guaranteed.

What does respond-async do?

respond-async asks the server to process the request asynchronously and reply immediately, typically with 202 Accepted and a status URL, instead of blocking until the work finishes. It is often paired with a wait token to bound how long the server may block first.

Is handling=strict the same as a Content-Type error?

No. handling=strict asks the server to reject the request if it cannot fully process every part of it, rather than silently ignoring unsupported bits. handling=lenient is the opposite: do the best you can and ignore what you do not understand.

What is the HTTP Prefer Header Reference?

Reference for HTTP Prefer request header tokens defined in RFC 7240: return=minimal, return=representation, respond-async, wait, handling=strict and handling=lenient, with the Preference-Applied response header. It runs free in your browser on Gera Tools, with nothing uploaded.

HTTP Prefer Header Reference

Name: HTTP Prefer Header Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Get one useful tool a week

Like this tool? Enter your email and we'll send you one genuinely useful Gera tool a week — plus a link to come back to this one. No spam, one-click unsubscribe any time.

What the Prefer header is for

The HTTP Prefer request header, defined in RFC 7240, lets a client express optional preferences about how the server should handle a request. Crucially, a preference is advisory: the server may apply it, partially apply it, or ignore it entirely, and the request must still succeed either way. This makes Prefer safe to send speculatively — you never break a request by asking for a behaviour the server does not support.

The registered preference tokens

Token	Effect when applied	Common use case
`return=minimal`	Server sends the smallest useful body (often 204 + Location)	Saving bandwidth on create/update
`return=representation`	Server echoes the full resulting resource in the response	Save a follow-up GET after writing
`respond-async`	Server replies with 202 Accepted + status URL immediately	Long-running operations
`wait=N`	Server may block up to N seconds before switching to async	Bound latency on async operations
`handling=strict`	Reject the request if any part cannot be processed	Strict validation
`handling=lenient`	Do the best you can, ignore unsupported parts	Tolerant parsing

How it works

A Prefer header carries one or more comma-separated preference tokens. Each token is either a bare keyword (respond-async) or a name=value pair (return=minimal, wait=10). Multiple preferences combine in one header:

Prefer: respond-async, wait=10, return=minimal

When the server honours a preference, it lists the applied tokens in a Preference-Applied response header so the client can confirm what happened. The registered tokens are respond-async, return (minimal or representation), wait (seconds), and handling (strict or lenient). Unknown tokens are simply ignored.

Worked examples

Avoiding a second GET after creation

Without return=representation, creating a resource typically requires a follow-up request:

POST /items
→ 201 Created
Location: /items/42

The client then fetches /items/42 to get the full record. With the preference:

POST /items
Prefer: return=representation
→ 201 Created
Location: /items/42
Content-Type: application/json
{...full item object...}

One round-trip instead of two. This is especially useful for mobile clients where latency is a concern.

Async processing with bounded wait

For a request that might complete fast or might be queued:

POST /reports/generate
Prefer: respond-async, wait=5

The server processes synchronously for up to 5 seconds. If it finishes in time, it returns 200 OK with the report. If not, it returns 202 Accepted with a polling URL. The client always gets a deterministic response within 5 seconds.

Tips

A server that varies its behaviour on Prefer should include Vary: Prefer in its response so caches do not serve one client’s minimal body to another client that wanted the full representation. Pair respond-async with wait to bound how long the server may block before switching to an async 202 Accepted response. Absence of a token in Preference-Applied means the preference was not applied — design your client to tolerate either outcome.