DEV Community: xushoulin

Unexpected token '<' in JSON at position 0? Your API returned HTML

xushoulin — Fri, 30 Oct 2026 02:39:55 +0000

A support ticket I have seen more than any other, in different disguises:
"The API works in Postman. In our app it throws Unexpected token '<' in JSON at position 0."
Every time, the same thing has happened: the app never received JSON. It received an HTML page, and the parser choked on the first character before it could learn anything about the payload.
That distinction sounds trivial. It costs people an afternoon, because the error message points at a character in a document that was never the problem.
Position 0 means "I never read a value"
A JSON document can only begin with one of seven things:
{ [ " - 0-9 t (true) f (false) n (null)
A strict parser reads the first non-whitespace character, checks it against that list, and stops immediately if it does not match.
An angle bracket matches nothing on that list. So the parser gives up before reading a value, reports position 0, and has no information about your data — because it never touched your data. The response is not malformed JSON. It is not JSON.
Which means: editing the payload will do nothing. The bug is upstream of the payload.
What actually arrived
Seven causes cover almost every case. The middle column is the part worth memorising, because it decides whether your code can even tell that something went wrong.
Cause
Body you received
How to recognise it
Route does not exist
HTML 404 page
Status 404, body starts with <!DOCTYPE or contains Cannot GET
Handler threw
HTML 500 page
Status 500, in development usually a stack trace
SPA catch-all rewrite
index.html, status 200
Any unknown path returns the app shell
Auth redirect
The login page
fetch followed the 302, so you get its 200
Reverse proxy / CDN
nginx, Cloudflare or LB page
502–504, server: nginx header, app never ran
Trailing slash mismatch
A 301, then the page
Check res.url, not the URL you requested
Wrong base URL
Whatever lives at that host
A typo, or http where you meant https
Only three of those come with a non-200 status. The other four are the interesting ones.
The 200 that lies
Deploy a static host with the standard single-page-app rewrite and every unknown path answers with the app shell and a 200.
So a request for a route that does not exist returns a response that looks perfectly healthy. fetch resolves. res.ok is true. res.statusText is OK.
The only thing that fails is res.json(), and its message blames a character.
This is the case where checking the status code cannot save you, because the status code is correct. What still tells the truth is the content-type header — which is why the fix below checks it before it parses anything.
Three ways to see the body in ten seconds
From a terminal. -i prints the status line and headers above the body, which is normally all you need:
curl -i -H 'Accept: application/json' https://api.example.com/v1/orders
Without re-running the request. clone() gives you a second readable stream:
const text = await res.clone().text();
console.log(res.status, res.headers.get("content-type"));
console.log(text.slice(0, 200));
In DevTools. Network panel, filter to Fetch/XHR, sort by status, open the failing row, read the Response tab. Not the Preview tab — Preview tries to render the body, and it will happily render a 404 page as if it were a document.
The rule that prevents the next one
Never call .json() on a response you have not inspected. Read the text, decide whether it is JSON, parse it yourself — so that when it fails, the error message contains evidence instead of a character.
async function readJson(res) {
const text = await res.text();
const type = res.headers.get("content-type") ?? "";

if (!type.includes("json")) {
throw new Error(
${res.status} ${res.url} returned "${type || "no content-type"}": +
text.slice(0, 120),
);
}
return JSON.parse(text);
}
The part that matters is text.slice(0, 120). The next time this happens, your log contains <!DOCTYPE html>

404 or a Cloudflare banner or a login form. That is a cause. A character is not.<br> Two smaller habits worth keeping:</p> <ul> <li>Treat 204 No Content as success with no body. It is the correct response to a DELETE, so a client that always calls .json() fails on a successful request. That failure has a different message — Unexpected end of JSON input — because an empty string has no first character to be unexpected.</li> <li>Strip a leading U+FEFF from anything that came from a file rather than the network. A byte-order mark is invisible in every editor, is not whitespace to a strict parser, and produces Unexpected token '', "{"a":1}" is not valid JSON — where the quoted character looks empty. "At position 0" is legacy wording I captured these by running each input through Node 22.22.2. None of them are paraphrased: Engine Message Node 22 / current V8 Unexpected token '<', "<!DOCTYPE "... is not valid JSON Older Chrome, Safari Unexpected token < in JSON at position 0 Firefox JSON.parse: unexpected character at line 1 column 1 of the JSON data Any engine, empty body Unexpected end of JSON input Any engine, plain-text error Unexpected token 'E', "Error: not found" is not valid JSON Current V8 no longer says "at position 0" — it quotes the first ten characters instead. That is why half the Stack Overflow answers you will find describe a message your browser stopped printing a few versions ago. The behaviour is identical; only the wording moved. Which leads to the practical rule: never parse the message. Catch the exception, treat it as "invalid", surface the text to a human. A regex against Unexpected token will break on the next runtime upgrade. If the response came from your own server Once you have the body, the cause is normally one of five, and every one of them is a routing or header problem rather than a JSON problem:</li> <li>The catch-all is registered before the API route. app.get("*") in Express 4, app.get("/*splat") in Express 5, or a static handler above the router, swallows the request and serves the shell.</li> <li>The error handler returns HTML. A framework's default error page does exactly that. If the request accepted JSON, answer with JSON.</li> <li>The rewrite rule covers too much. /* → /index.html must exclude your API prefix.</li> <li>Auth is handled by a redirect. A session guard answers an expired token with a 302 to the login page. An API should answer 401 and let the client decide.</li> <li>A proxy owns the error. If the body is stamped nginx or Cloudflare, your application never ran. Look at upstream health, not at code. The one-line version If the first byte of the body is { or [, it is JSON and the mistake is inside it. If it is <, it is a web page and the mistake is in your routing, your auth, or your base URL. Everything else in this post is a consequence of that sentence. I run a small set of browser-only JSON tools — formatter, validator, diff, minifier — and a longer version of this post, with the full table of engine differences, lives here: Unexpected token '<' in JSON at position 0. Nothing is uploaded; the parsing happens in the tab.</li> </ul>

devto-post-1-precision

xushoulin — Fri, 23 Oct 2026 06:04:21 +0000

A support ticket I keep seeing, in various disguises: "the ID changed after we formatted the JSON." It didn't change because of the formatter. It changed the moment the document was parsed, before any tool could intervene.

Here is the whole failure in one line:

JSON.parse('{"id":9007199254740993}').id
// 9007199254740992

Nothing was malformed. The container was too small.

The spec allows it; the runtime does not

RFC 8259 does not put a size limit on numbers. It explicitly permits implementations to set limits on range and precision, and it warns that integers outside ±(2^53 − 1) "indicate potential interoperability problems."

That sentence is the entire story. The format happily carries a 20-digit integer. The runtime almost everyone parses it with cannot hold one, because JavaScript has exactly one numeric type: a 64-bit float. Every number literal in a JSON document becomes a double before your code sees it.

So the document is valid, the parser is correct, and the value is wrong.

Where the boundary actually is

Number.MAX_SAFE_INTEGER is 9007199254740991, which is 2^53 − 1. An integer at or below that is represented exactly.

The next integer, 9007199254740992, is 2^53 and is still exact — powers of two always are. But 9007199254740993 does not exist as a double. It rounds down to 9007199254740992, and so does every odd integer after it, until the next power of two where the spacing widens again.

This is why the bug survives code review. An 18-digit snowflake ID sits comfortably inside the range of a 64-bit integer and comfortably outside the range of a double. The two ranges overlap just enough for everyone to assume they're the same range.

What a round trip actually changes

I ran the same document through JSON.parse and then JSON.stringify — which is exactly what "format" means — and recorded every difference.

Input	After round trip	Why
`{"id":9007199254740993}`	`{"id": 9007199254740992}`	Numbers become IEEE-754 doubles. Integers above 2^53 lose their last digits.
`{"b":1,"2":2,"1":3}`	`{"1": 3, "2": 2, "b": 1}`	Keys that look like array indices are enumerated first, ascending. That is a JavaScript object rule, not a JSON one.
`{"a":1,"a":2}`	`{"a": 2}`	Duplicate member names collapse silently: the last value wins and the others are gone.
`{"x":1.0,"y":1e3,"z":-0}`	`{"x": 1, "y": 1000, "z": 0}`	Numbers are re-printed in their shortest round-trippable form.
`"\u00e9\/"`	`"é/"`	Escapes are decoded, then only the ones that must be escaped are written back.

Only the first row is real information loss. The other four are normalisation: the bytes differ, the meaning does not.

That distinction matters more than it looks. If you diff two documents that have both been through a formatter, you will get a report of changes no human made — reordered keys, 1.0 becoming 1, an escaped slash becoming a plain one. I built a JSON diff tool around this, and the "ignore key order" toggle exists precisely because of row two.

Object key order is not insertion order

Row two is the one people rarely expect. A JavaScript object enumerates integer-like keys first, in ascending numeric order, then the remaining string keys in insertion order.

{"b":1,"2":2,"1":3} therefore comes back as {"1":3,"2":2,"b":1} — and no, that is not a bug in the formatter. JSON itself defines no order at all; it is a set of name/value pairs. Any consumer depending on member order was relying on undefined behaviour from the start.

If order is part of your payload, put it in the data: an array of objects with an explicit position field, not the order the bytes happened to arrive in.

Three ways to keep big integers intact

In order of how much you should prefer them.

1. Make the field a string in the API. This is what large platforms do. {"id":"9007199254740993"} is unambiguous, survives every parser on every platform, and costs one pair of quotes. Nobody downstream has to remember a rule.

2. Intercept the parse with a reviver. A reviver can inspect each value before your code sees it. Recent V8 engines pass a third argument that exposes the raw literal, which is what makes this reliable instead of guesswork:

JSON.parse(text, (key, value, context) => {
  // context.source is the literal exactly as written in the document.
  const raw = context?.source;
  if (typeof value === "number" && !Number.isSafeInteger(value)
      && raw && /^-?\d+$/.test(raw)) {
    return BigInt(raw);
  }
  return value;
});

I verified this on Node 22.22.2 — context.source really does hold "9007199254740993" before the double conversion wins. But feature-detect it rather than trusting it: if context is undefined, the engine predates the feature and the digits are already gone. In that case fall back to option 1 or 3.

3. Use a lossless parser. Libraries like lossless-json keep the original text of each number and hand you a wrapper type. They work everywhere, at the cost of a dependency and a value type nobody on your team has seen before.

If you hash or sign JSON

A round trip is not byte-stable, so never re-serialise a payload that was signed.

Two documents can be semantically identical and hash differently because of whitespace, key order, or number formatting — 1.0 and 1 are the same float and different bytes. A payload that went through JSON.parse and back may no longer match its own signature, and the failure looks like a corrupted message rather than a formatting difference.

Sign the exact bytes you send: serialise once, hash that string, transmit the same string. On the receiving side, verify before parsing, not after.

The short version

JSON allows numbers of any length; JavaScript has one numeric type, and it's a float.
The safe range is ±(2^53 − 1). Snowflake IDs sit just outside it, which is why this bites production systems and not tutorials.
Strings for IDs. Always.
A formatter can't fix this, because the damage happens inside the parse. Any tool claiming to preserve 9007199254740993 as a number is lying about what the runtime holds afterwards.

The full version, with the same measurements and a few more cases, is at shoulin.shop/guides/why-json-numbers-lose-precision. If you want to watch the loss happen to your own payload, the formatter runs entirely in the tab — no upload, no account, and the Network tab will show you nothing leaving.