The JSON mistakes that break APIs (and how to spot them fast)

Plenty of API failures blamed on mysterious backend behaviour trace back to a single stray character. JSON's grammar is tiny and strict: one misplaced comma invalidates the entire document, and the resulting error message frequently points at a location far removed from the true crime. The consolation is that malformed payloads fall into a handful of recurring traps, learnable in one sitting. Master them and you will read parser errors like a native speaker instead of diffing entire payloads by eye at midnight before a release. Every trap below has consumed someone's evening; none of them needs to consume yours.

Trailing commas

JavaScript object literals tolerate a comma after the final property; JSON forbids it outright. Per the specification, a comma may appear only between members, so {"a":1,"b":2,} is invalid even though every browser console accepts it cheerfully. The mistake breeds wherever objects get assembled by hand: template strings, configuration files, test fixtures copied out of running code. The parser's complaint — expecting a property name where the closing brace sits — is technically accurate yet baffling if you have never encountered strict grammar before. When moving objects out of JavaScript into request payloads or fixtures, delete that final comma as a reflex. Linters configured for strict JSON catch it automatically; human eyes, exhausted at the end of a long day, routinely do not.

Quote problems, three flavours

JSON permits exactly one string delimiter: the straight double quote. Everything else fails. {'name':'Ada'} errs twice — keys require double quotes, and bare identifiers are not permitted at all, so {name:"Ada"} fails equally. The sneakiest variant arrives through copy-paste: documentation sites and blogs typeset code samples with typographic quotes — “curly” marks like these — which look nearly identical to legal characters but carry entirely different byte values. Parsers reject them with bewildering complaints about unexpected tokens on lines that appear flawless. Any snippet lifted from a formatted article, PDF or slide deck deserves a quote audit before it touches a live request. Replace every curly mark with straight ones and a large share of mystery failures evaporate immediately.

Unescaped newlines inside strings

A JSON string cannot contain a raw line break; it must be escaped as \n. Multi-line values assembled through string concatenation, or pasted from editors that preserve formatting, frequently smuggle literal newlines inside quoted values. The parser then reports an unterminated string anchored at the true start of the value — a line number well upstream of where you suspected trouble. Literal backslashes in Windows paths and unescaped embedded quotes belong to the same family of escapes-gone-missing. Hand-building JSON invites all of them eventually; constructing objects in code and serialising mechanically eliminates the category entirely, because the serialiser performs every escape correctly without supervision.

Numbers pretending to be strings

{"age":"31"} parses cleanly and then detonates downstream, because the receiving schema expects numeric comparison, sorting or validation. Quoted numbers are the leading cause of type mismatches crossing language boundaries: JavaScript quietly coerces and hides the bug, Java throws an exception, Python compares oddly, and everyone spends an hour blaming the network layer. The reverse traps exist too — identifiers that look numeric must remain strings, since leading zeros silently evaporate and very long digit runs lose precision beyond the safe integer range of some runtimes. Decide types deliberately at the boundary, encode them consistently, and validate incoming payloads against a schema before business logic ever sees them.

JSON riding in query strings

Embedding JSON in URLs — search filters, webhook configurations, deep links — fails without percent-encoding. Braces, quotes, colons and spaces all carry reserved meanings in URL grammar; worse, an ampersand inside unencoded JSON splits the query string into phantom parameters, so the receiving side perceives truncated data and begins debugging entirely the wrong layer. Encode the complete payload — {"q":"chai"} becomes %7B%22q%22%3A%22chai%22%7D — or relocate the data into a request body where it structurally belongs. A dedicated URL encoder completes the job in seconds and permanently retires the class of mystery truncation bugs that waste otherwise-rational engineers.

Two things JSON simply refuses

Some editors on Windows open and re-save files with a byte-order mark prefixed — a few invisible bytes rendered as nothing in every viewer, sitting ahead of the opening brace. Strict parsers treat the mark as garbage preceding the document and fail with unexpected-token errors on files that look absolutely immaculate. Pipelines mixing operating systems encounter this intermittently, which lends the bug an eerie, haunted reputation; re-save suspicious files as plain UTF-8 without BOM, or strip leading bytes programmatically at ingestion boundaries. Comments are the second refusal. Developers accustomed to friendlier configuration formats expect annotations and sprinkle slash-slash remarks into JSON files, yet plain JSON defines no comment syntax whatsoever — parsers halt at the first slash they meet outside a string. Several ecosystems tolerate JSONC dialects that permit remarks, but a strict API endpoint will not, and assuming leniency the specification never promised is how Friday deployments acquire their best war stories.

Pinpointing errors by line and column

This is where a formatter earns its keep. Strict parsers report failure position as a line and column, and a capable formatter surfaces that pointer immediately alongside highlighted offending tokens. Instead of scanning hundreds of lines for a missing brace, paste the payload, press format, and jump straight to the reported coordinate — the culprit usually sits within a few characters of the marker even when the root cause began earlier in the document. Two minutes of mechanical inspection routinely replaces an hour of console archaeology, and unlike squinting, the approach scales gracefully to minified payloads nobody formatted by hand.

A sixty-second pre-flight check

Before shipping any hand-built payload, run it through this list:

• Remove any comma after the last property or array element.
• Convert every quotation mark to a straight double quote, keys included.
• Escape newlines, tabs and embedded quotes inside string values.
• Confirm numeric fields carry no surrounding quotes.
• Percent-encode anything travelling inside a URL.
• Re-save suspicious files as UTF-8 without BOM.