What Is Content Negotiation in HTTP?

Content negotiation lets a client and server agree on the best representation of a resource to return, based on headers like Accept, Accept-Language, and Acc...

Published November 17, 2026

Content negotiation lets a client and server agree on the best representation of a resource, such as JSON vs XML, language or compression, using request headers like Accept, Accept-Language and Accept-Encoding.

The concept

The client lists what it can handle with preferences (q values). The server picks one and tells the client in Content-Type, Content-Language or Content-Encoding.

If nothing acceptable exists, the server may answer 406 Not Acceptable. The Vary header tells caches which request headers affected the response.

Ask and answer

→ Accept: application/json, text/html;q=0.5
→ Accept-Language: en-IN, hi;q=0.8
→ Accept-Encoding: gzip, br
← Content-Type: application/json Content-Encoding: br

Practical examples

Request JSON

curl -H 'Accept: application/json' https://api.example.com/users/7

Server branch (Express)

app.get('/users/:id', (req, res) => {
  res.format({
    'application/json': () => res.json(user),
    'text/html': () => res.send(`<h1>${user.name}</h1>`),
    default: () => res.sendStatus(406),
  })
})

Tell caches

Vary: Accept, Accept-Encoding

Common mistakes

  • Forgetting the Vary header and serving the wrong cached variant.
  • Ignoring q-values.
  • Returning HTML errors to JSON clients.

Key takeaways

  • Client states preferences, server chooses.
  • Accept, Accept-Language, Accept-Encoding.
  • Use Vary for caches.

FAQ

What is 406?

The server cannot produce any format the client accepts.

Is URL-based versioning negotiation?

No; it is a different strategy (/v1/).

More HTTP articles