JSON MIME Type: Content-Type, +json, and API Errors

Content-Type, Accept, and response Content-Type are different

Most JSON header incidents are not spelling mistakes. They happen because a client, a server, or a proxy applies a correct header in the wrong direction of the exchange. This guide is for developers debugging a real request, where the request body, declared type, response body, and response type all need to agree.

A useful counterexample is a GET request with no body. It usually needs no request Content-Type at all. Adding Content-Type: application/json does not ask the server for JSON; that is the job of Accept. Even then, the server may return HTML, CSV, or a JSON problem document, so check the actual response header before parsing.

application/json and UTF-8: the strict API edge case

For an ordinary JSON representation, use application/json. The IANA registration is the registry entry behind that value. RFC 8259 says JSON exchanged between systems outside a closed ecosystem must be UTF-8. UTF-8 is therefore the interoperable default, not a value a client should guess from an operating system locale.

You will still see application/json; charset=utf-8 in production. Many frameworks emit it and most clients accept it. The detail that catches teams is that the IANA registration defines no charset parameter for application/json; a compliant recipient does not need it to discover JSON encoding. A strict endpoint that compares the whole string to application/json can reject an otherwise usable request with 415 Unsupported Media Type.

What the +json suffix means

A type ending in +json is not a typo for application/json. It is a structured syntax suffix defined by RFC 6839. The suffix tells a generic client that the representation uses JSON syntax while the complete media type keeps its more specific contract.

Treat the suffix as a parsing signal, not permission to ignore the schema. application/problem+json is JSON, but it describes an error according to RFC 9457. A success parser that assumes a data or items field will still fail on a valid problem document.

Send JSON correctly from curl, Node, and Python

These examples make the body and headers agree. Replace the example URL with an endpoint that accepts JSON. Once a curl request works, use the cURL Converter to create equivalent client code.

curl: show response headers and body

curl -i https://api.example.test/items \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{"name":"ByteJSON"}'

The -i flag matters during debugging. It proves whether the server actually returned JSON, HTML, or a +json problem document. Do not infer a response type from the header you sent in the request.

Node and Express

app.use(express.json());

app.post("/items", (req, res) => {
  res.status(201).json({ id: "item_123", name: req.body.name });
});

const response = await fetch("/items", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/json" },
  body: JSON.stringify({ name: "ByteJSON" }),
});

In Express, res.json() serializes a value and sets a JSON response type. On the client, JSON.stringify and the request Content-Type are a pair. Setting the header while sending a JavaScript object directly does not create a JSON body.

Python requests

import requests

response = requests.post(
    "https://api.example.test/items",
    json={"name": "ByteJSON"},
    headers={"Accept": "application/json"},
    timeout=10,
)

response.raise_for_status()
print(response.headers.get("content-type"))
print(response.json())

In requests, json= serializes the value and supplies the JSON content type. data= has different semantics and is appropriate only when you deliberately control the encoded body.

How to fix 415 Unsupported Media Type and parser failures

const response = await fetch("/api/items");
const mediaType = (response.headers.get("content-type") || "")
  .split(";", 1)[0].trim().toLowerCase();

if (!response.ok) {
  const detail = mediaType === "application/json" || mediaType.endsWith("+json")
    ? await response.json() : await response.text();
  throw new Error("Request failed: " + response.status + " " + JSON.stringify(detail));
}

if (mediaType !== "application/json" && !mediaType.endsWith("+json")) {
  throw new Error("Expected JSON, got " + (mediaType || "no Content-Type"));
}
const data = await response.json();

A JSON Content-Type debugging checklist

1. 1.Inspect raw request and response with devtools or curl -i, including status, headers, and body.
2. 2.Confirm the body is valid JSON before checking media types. A correct header cannot repair malformed syntax.
3. 3.Match the endpoint contract: JSON, form encoding, and multipart uploads are different formats.
4. 4.Compare the media type portion when parameters are allowed, while keeping endpoint-specific allowlists explicit.
5. 5.Accept documented +json responses deliberately and parse them according to their specific contract.
6. 6.When a response is not JSON, log a bounded text preview and status instead of calling response.json blindly.