How to debug an API JSON response step by step
A repeatable workflow for separating transport errors, JSON syntax problems, and data-contract failures in API responses.
A response that looks like broken JSON may actually be an HTML error page, a proxy message, compressed data, or a valid payload with the wrong shape. Debug the response in layers instead of changing the client until the error disappears.
Keep a sanitized copy of the raw status, headers, and body. Formatting too early can hide truncation, duplicate-looking fields, encoding problems, or the exact byte where parsing failed.
Check HTTP before parsing JSON
Confirm the status code, Content-Type, Content-Encoding, and character set. A 200 response can still contain a login page, while a useful JSON error may arrive with 400 or 500.
Reproduce the request with cURL and compare method, URL, query parameters, body, authentication, and Accept headers with the failing client.
Separate syntax from the data contract
Format the untouched body. If parsing fails, inspect trailing commas, unescaped quotes, control characters, partial output, and text before or after the JSON document.
If parsing succeeds, validate required fields, nullability, number-versus-string types, enums, and nested arrays against the documented schema.
Compare a known-good response
Diff a failing response against a sanitized working sample after removing volatile IDs and timestamps. Structural changes are usually more important than whitespace or key order.
{:"Record the smallest input that reproduces the issue and the layer that introduced it"=>"client, application, proxy, CDN, or upstream service."}
API response debugging checklist
- Save the raw status, headers, and body before formatting.
- Confirm Content-Type and encoding match the actual body.
- Reproduce the request outside the failing client.
- Validate JSON syntax separately from the API schema.
- Compare types, nulls, required fields, and array shape.
- Remove tokens and personal data before sharing examples.
Related guides
Learn the workflow behind this tool and what to check next.
How to debug JSON API payloads
A practical workflow for formatting JSON, finding syntax errors, validating payload shape, and checking response status when API data looks wrong.
How to debug JWT authentication safely
A security-aware workflow for separating token structure, claim validation, signature verification, and authorization decisions.
How to clean CSV data before import
A safe CSV cleanup workflow that preserves the original file and turns import assumptions into explicit checks.