JSON APIs: Request Handling and Content-Type Headers

The header that actually tells the server what to expect

An HTTP request body is just bytes — nothing about the bytes themselves says "this is JSON." The Content-Type: application/json header is what explicitly declares it, and most frameworks route request parsing based on that header, not by guessing from the payload. Send a JSON body with Content-Type: text/plain (or omit the header) and many servers will simply treat it as raw text, never attempting to parse it as JSON at all — a request that looks correct in every other way can fail purely because of this one header.

Accept vs. Content-Type — two different headers, easy to confuse

• Content-Type describes what the request body actually is — set by whoever is sending data.
• Accept describes what response format the client is willing to receive — set by the requester, independent of what they're sending.

A client can send Content-Type: application/json (its request body is JSON) while setting Accept: application/json (it also wants a JSON response) — these are two separate declarations, and mixing them up (or omitting one) is a common source of "the API returned XML/HTML when I expected JSON" confusion, since some APIs default to a different format when Accept isn't set as expected.

Common JSON API response conventions

Most JSON APIs return errors as JSON too, not as plain text — a typical convention:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Field 'email' is required"
  }
}

But conventions here vary significantly by API — some nest under error, others use errors (plural, for multiple issues), and some just return a flat object with a message field. There's no single universal standard the way there is for the Content-Type header itself — always check a specific API's documented error shape rather than assuming.

Common mistakes

• Sending a JSON body without setting Content-Type: application/json. Many server frameworks won't attempt JSON parsing without this explicit signal, regardless of what the body actually contains.
• Confusing Accept and Content-Type. One describes what you're sending, the other what you want back — they're independent and both matter for a JSON-in, JSON-out request.
• Assuming every API's error response shape is the same. There's no universal JSON error format — check the specific API's documentation.

FAQ

Why does my API request fail even though the body is valid JSON?
Check the Content-Type header — without application/json explicitly set, many server frameworks never attempt to parse the body as JSON in the first place.

What's the difference between Content-Type and Accept headers?
Content-Type describes the format of the data you're sending; Accept describes the format you want back in the response — they serve different, independent purposes.

Is there a standard JSON format for API error responses?
No universal standard — conventions vary by API (nested under error, errors, or a flat object); always check the specific API's own documentation.

Format and inspect JSON API payloads with the JSON Toolkit — runs entirely in your browser.