2026-09-11 · 6 min read · Rahul Chitturi
- json
- http
- api-debugging
An API request can succeed with HTTP 204 No Content and still trigger a client error when a shared wrapper calls response.json() unconditionally. The parser receives zero bytes, so the failure is not malformed JSON inside the response; there is no JSON document to parse.
Similar symptoms occur with 200 responses whose bodies are accidentally empty, HEAD requests, proxies that remove content, and clients that hide the original status before decoding.
Inspect the response before parsing
Capture the method, final URL, status, redirect history, relevant content headers, and actual byte length with a harmless fixture. Decide whether the endpoint contract promises JSON for that status rather than guessing from Content-Type alone.
- Treat 204 and HEAD responses as bodyless.
- Do not send a JSON literal such as null with status 204.
- Investigate an empty 200 response as a separate contract violation.
- Preserve the status when a wrapper returns decoded data.
Make decoding status-aware
Branch on the response contract before calling a JSON parser. Return a deliberate no-content result for bodyless success statuses, parse expected JSON bodies, and classify non-success responses using their documented media type.
Avoid catching every syntax error and converting it to null. That hides truncated responses and malformed JSON that should fail loudly.
Reproduce with safe Flashman fixtures
Use the JSON formatter for synthetic response bodies, diff for wrapper outputs, URL tool for request targets, and timestamp converter for sanitized traces. Do not paste authorization headers, cookies, or private payloads.
Test 200, 201, 202, 204, 205, 304, HEAD, redirects, chunked responses, content-length mismatches, malformed error bodies, aborted transfers, and each generated API client used in production.