The 7 JSON errors that break your API (and how to fix each one)

"Unexpected token } in JSON at position 247." Few messages waste more developer time. It tells you a parser gave up, roughly where, and nothing at all about what to change.

Almost every invalid JSON document fails for one of seven reasons, and six of them come from writing JavaScript out of habit. JSON is a strict subset of JavaScript's object syntax: everything JSON allows is valid JavaScript, but a great deal of valid JavaScript is not JSON.

1. Trailing commas

A comma after the last item in an object or array. Modern JavaScript allows it — it makes diffs cleaner — and JSON forbids it outright. This is the single most common failure, and the most maddening, because the code that produced the JSON often accepts it happily.

The fix is to remove the comma before the closing brace or bracket. If you are generating JSON in a loop, use your language's serialiser rather than assembling the string by hand.

2. Single quotes

JSON requires double quotes on every string and every key. 'name' is a JavaScript string and a JSON syntax error. Parsers usually report this as an unexpected token at the quote position, which is unhelpfully vague if the document is long.

3. Unquoted keys

JavaScript permits { name: "x" }. JSON requires { "name": "x" }. Every key is a quoted string, without exception — including keys that look like perfectly ordinary identifiers.

4. Comments

JSON has no comment syntax, and that was a deliberate decision by its author to keep parsers simple. // and /* */ both break it. If you need comments in a config file, use JSONC or JSON5 — but only if whatever reads the file supports them. The common workaround in strict JSON is a dummy "_comment" key.

5. NaN, Infinity and undefined

These are JavaScript values with no JSON equivalent. JSON.stringify silently drops undefined properties and converts NaN to null, which means a round trip can quietly change your data rather than failing loudly. Use null explicitly, or a string, depending on what the consumer expects.

6. Unescaped control characters

A literal newline inside a string is invalid; it must be written as \n. The same applies to tabs, double quotes and backslashes. This one usually appears when a multi-line value has been pasted into a config file by hand.

7. A byte-order mark

Some Windows editors prepend an invisible BOM when saving as UTF-8. The file looks perfect and the parser fails at position 0, which is a genuinely confusing combination. Save as "UTF-8 without BOM" and it goes away.

The eighth problem, which produces no error at all

Duplicate keys. The specification neither permits nor forbids them, and does not say what should happen. In practice JavaScript's parser keeps the last occurrence and silently discards the earlier ones.

That silence is the danger. Data can disappear with no error anywhere — so if a value is inexplicably missing from a parsed object, look for a duplicate key earlier in the document.

Habits that prevent all of this

• Never build JSON with string concatenation. Use your language's serialiser — hand-assembled JSON breaks the first time a value contains a quote.
• Validate before you ship, not after a deploy fails.
• Store dates as ISO 8601 strings. They sort correctly as text and are unambiguous about time zone.
• Send large integers as strings. JSON numbers are IEEE 754 doubles in JavaScript, so anything above 2^53 loses precision silently.
• Keep key naming consistent across an API. Mixed camelCase and snake_case causes real bugs at integration boundaries.