How to debug JSON APIs

July 26, 2026 · 14 min read

JSON APIs fail in predictable layers: bytes on the wire are not valid UTF-8, the parser rejects the text, or the parser succeeds but your application rejects the shape. Skipping straight to business logic debugging wastes hours. Work top-down: valid bytes, valid JSON, valid schema, then valid semantics.

Parse errors first

Trailing commas, single-quoted keys, and unescaped newlines in strings are illegal in JSON but common in JavaScript object literals. A validator pinpoints the line and column. If parsing fails only in production, compare Content-Type charset and whether a middleware truncated the body.

// Invalid: trailing comma (JSON.parse rejects)
{ "id": 1, "name": "Ada", }

// Valid
{ "id": 1, "name": "Ada" }

Schema and types

OpenAPI or JSON Schema documents expected types. A number sent as a string passes JSON.parse but fails validation. Nullable fields and oneOf unions are frequent sources of 400 responses that look random until you validate the sample against the schema.

Encoding and charset

Always declare charset=utf-8 in JSON responses. BOM-prefixed files break naive parsers. When integrating with legacy systems, watch for Latin-1 mislabeled as UTF-8 - mojibake in names and addresses is a classic symptom.

Logs and reproduction

Log body length and a SHA-256 hash alongside a redacted preview. Reproduce with curl using --data-binary @file.json to avoid shell escaping bugs. Store failing payloads in a ticket (redacted) so the next engineer does not re-hunt.

CI guardrails

Run schema validation on golden fixtures in CI. Fuzz optional fields. Test empty objects and empty arrays - serializers often treat them differently. Document whether your API uses JSON null versus omitted keys; clients will send both.

FAQ

Why does JSON.parse work in Node but fail in the browser?: Usually different input bytes - copy-paste truncation, BOM, or a non-JSON prefix like XSSI guards )]}',
Should APIs accept comments or trailing commas?: Strict JSON (RFC 8259) says no. If you want lenient parsing, document it explicitly - do not assume all clients match.
How big is too big for a JSON body?: Depends on your server and parser limits. Set max body size at the reverse proxy and stream large payloads instead of single giant documents.

Browse all tools