Reading and Debugging JSON API Responses

Sooner or later, anyone working with web applications ends up staring at a wall of JSON: a payment gateway response, a webhook payload, an error from a partner's API. Raw JSON often arrives as a single unbroken line that is almost impossible to read. A JSON formatter turns it into an indented, readable structure, and that is the first step in debugging. This guide covers how to read JSON confidently, the errors that break it, and a systematic way to find out why an API call is not doing what you expect.

JSON in one minute

JSON (JavaScript Object Notation) is a text format for structured data, used by most modern web APIs. It has only a few building blocks:

• Objects: unordered sets of named values in curly braces, such as {"name": "Asha"}.
• Arrays: ordered lists in square brackets, such as [1, 2, 3].
• Values: strings in double quotes, numbers, true, false, null, or nested objects and arrays.

Here is a typical compact API response:

{"order":{"id":10482,"status":"paid","items":[{"sku":"CHR-01","qty":2,"price":"1499.00"}],"customer":{"email":"asha@example.com","phone":null}}}

And the same data after formatting:

{
  "order": {
    "id": 10482,
    "status": "paid",
    "items": [
      { "sku": "CHR-01", "qty": 2, "price": "1499.00" }
    ],
    "customer": {
      "email": "asha@example.com",
      "phone": null
    }
  }
}

Indentation reveals the hierarchy at a glance: one order, containing a list of items and a customer.

Where to find a JSON formatter

• Browser developer tools. In the Network tab, select a request and open its Response or Preview pane. Most browsers display JSON as a collapsible tree. Firefox also formats JSON automatically when you open an API URL directly.
• Code editors. Most editors can format a JSON document with a single command.
• Command line. The jq utility formats and filters JSON: curl -s https://api.example.com/orders/10482 | jq .
• Programming languages. PHP's json_encode($data, JSON_PRETTY_PRINT) or JavaScript's JSON.stringify(data, null, 2) produce readable output for logs.
• In the browser. Our JSON formatter and Base64 decoder formats or minifies JSON and shows where a parse error is. It runs entirely in your browser, so the response is never uploaded anywhere.

Be careful pasting production responses into online formatters that send data to a server. They may contain personal data, tokens or keys. Use local tools, or ones that run only in your browser, for anything sensitive.

Common JSON syntax errors

If a formatter or your code reports "invalid JSON" or "unexpected token", one of these is usually to blame:

The last case is the most common in practice. When code expecting JSON receives an HTML page from a crashed server, a login redirect or a proxy error, the parser fails on the first character. Always look at the raw response before assuming the JSON itself is malformed.

A systematic way to debug an API response

1. Check the status code

The HTTP status code tells you the outcome category before you read the body. Codes in the 200s mean success; 400 usually means your request was malformed; 401 means authentication is missing or wrong; 403 means you are authenticated but not allowed; 404 means the resource or endpoint does not exist; 422 often means validation failed; 429 means you hit a rate limit; 500s mean the server failed.

2. Check the headers

Confirm Content-Type is application/json. Look for rate-limit headers, request IDs (quote these when contacting the API provider) and caching headers that might be serving a stale response. You can inspect a URL's headers with our HTTP header checker, or with curl -i.

3. Read the error body

Good APIs return structured errors, often with a code, a human-readable message and the field at fault. Read the whole thing; the clue is frequently in a nested details array.

4. Compare request with documentation

Check the exact field names, nesting and types the documentation expects. A field sent as "qty": "2" (a string) when the API expects 2 (a number) can fail validation or, worse, be silently ignored.

5. Reproduce outside your application

Send the same request with curl or an API client. If it fails there too, the problem is in the request or the API; if it succeeds, the problem is in how your code builds or handles it.

Data-type traps

• Missing versus null. A field that is absent and a field that is null can mean different things. Code should handle both.
• Large numbers. JavaScript cannot represent very large integers exactly, so long numeric IDs can be silently altered when parsed. Many APIs send such IDs as strings for this reason.
• Money as strings. Prices are often sent as strings like "1499.00" to avoid floating-point rounding. Convert them with a decimal-safe method, not a quick float conversion.
• Dates and time zones. Check whether timestamps are ISO 8601 strings, Unix timestamps or local times, and which time zone applies.
• Encoded content. Some fields contain Base64-encoded data, such as file contents or the payload section of a JSON Web Token. Decode them with a tool like our Base64 encoder and decoder to see what is inside, remembering that Base64 is encoding, not encryption.
• Character encoding. JSON should be UTF-8. Garbled accented or non-Latin characters usually point to an encoding mismatch somewhere in the chain.

Logging JSON safely

Logging API requests and responses makes debugging far easier, but mask passwords, tokens, card details and unnecessary personal data before writing logs. Include a correlation ID so you can match your log entry with the provider's records. Teams building web applications with several integrations benefit greatly from consistent, structured logs.

Key takeaways

• Format JSON before reading it; use local tools for sensitive data.
• "Invalid JSON" often means the server returned HTML or an error page.
• Debug in order: status code, headers, error body, documentation, then reproduce outside your app.
• Watch for null versus missing, large IDs, money as strings, dates and encoded fields.