A JSON parser complains about the first character of an API response. You reformat the request, retry it, and get the same error. Before changing the JSON, check whether the response is JSON at all. A login page, a proxy error, or an application fallback can arrive where your code expects an object.

This is the first article in Toolzify's Workflow Lab: small, reproducible investigations you can adapt to your own project. The example below uses fictional response data. It separates a transport problem from a syntax problem so that fixing one does not conceal the other.

Keep the response before parsing it

Consider this response body:

<!doctype html><title>Sign in</title>

It is a small HTML document, not a malformed JSON object. Passing it to JSON.parse throws a SyntaxError. The exact error wording depends on the JavaScript engine, so write checks against behavior rather than a particular sentence. Formatting the HTML differently cannot turn the response into the API contract you expected.

In your browser's Network panel, select the request and inspect its final URL, HTTP status, response headers, and response body. A redirect may have sent you to a sign-in page. A reverse proxy may have returned its own error document. A development server may have served the frontend application's HTML fallback for an unknown route. These are possibilities to investigate, not a diagnosis made from the parser error alone.

Read once, then inspect deliberately

This helper checks the response status and media type before parsing a body. It accepts ordinary application/json and structured JSON media types ending in +json. It deliberately does not log the response body: error documents and API replies can contain private information.

async function readJsonResponse(response) {
  const raw = await response.text();
  const type = (response.headers.get('content-type') || '')
    .split(';')[0].trim().toLowerCase();
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  if (!(type === 'application/json' || type.endsWith('+json'))) {
    throw new Error(`Expected JSON; received ${type || 'no media type'}`);
  }
  return JSON.parse(raw);
}

The helper consumes the body as text and parses that text once. Do not follow it with response.json on the same response. A successful HTTP status is only one check; a server can still send the wrong representation. Conversely, an error response might contain useful JSON error details. If your application needs those details, add an explicit error-response branch that follows its documented contract.

Test the failure boundaries

Use JavaScript Response objects to exercise the helper without a real account or API token. With status 200, Content-Type application/json, and body {"ok":true}, it should return an object whose ok property is true. With status 200 and text/html, it should reject the representation. With status 503, it should report the HTTP failure before pretending that the request succeeded. Finally, a JSON media type with an unfinished body such as {"ok": should still fail at JSON.parse.

These tests answer different questions. They do not establish whether the returned object has all required fields, whether a user is authorized, or whether the backend completed a business operation. Add those checks where your application's contract requires them.

Use a formatter at the right point

Once you have confirmed that the payload is intended to be JSON, paste a small, redacted example into the JSON Formatter. Format it to inspect nesting, or validate its syntax. Keep request IDs and field names that matter to the investigation, but replace credentials, email addresses, and customer values with fictional data. Read the formatting and meaning guide before relying on a parsed-and-serialized copy for large numeric identifiers or signatures.

Leave a useful investigation note

Record the route you expected, the final route you observed, the status, the media type, and the smallest safe reproduction. State which layer needs a change: request routing, authentication, proxy configuration, server serialization, or client validation. That note is more useful than “the JSON tool failed” because it lets another developer reproduce the boundary that actually broke.

Next in Workflow Lab: resize and compress an image with a checkable comparison, then verify a Unicode-to-Base64 round trip.

References: MDN: JSON.parse and RFC 8259: JSON. The response checks above are Toolzify examples, not quoted source code.