How to Debug an API JSON Response
When an API client says it “cannot parse JSON,” the JSON syntax may not be the real problem. Authentication redirects, HTML error pages, empty bodies, proxy failures and unexpected content types frequently surface as JSON parser exceptions.
Quick answer
Inspect the HTTP response before changing your parser: status code, final URL, Content-Type header and raw body usually reveal whether the server actually returned JSON.
1. Check status before parsing
A 401, 403, 404, 429 or 500 response may use a different body format than successful responses. Do not assume every status returns the same JSON shape.
2. Inspect Content-Type and raw body
If Content-Type is text/html and the body begins with <!doctype or <html>, fix the endpoint, authentication flow, proxy or server error instead of modifying JSON.parse.
3. Separate syntax from shape
Once the body is confirmed as JSON, validate its syntax. If it parses but your application still fails, compare the actual fields and types with the expected JSON Schema or TypeScript model.
Debugging checklist
HTTP status: 200?
Final URL: expected endpoint?
Content-Type: application/json?
Body empty?
Body starts with < ?
JSON syntax valid?
Expected fields and types present?Related JSON tools and guides
Frequently asked questions
Why do I get Unexpected token < from an API?
The response is often HTML rather than JSON, commonly from a 404 page, login redirect, proxy error or framework error screen.
Should I parse every API response as JSON?
No. Check the status and content type, and handle empty or non-JSON responses intentionally.
What if the JSON is valid but my app still breaks?
Validate the data shape and types against the contract your application expects.