2026-09-03 · 6 min read · Rahul Chitturi
- http
- json
- debugging
A client can report an unexpected JSON token even when the server produced valid JSON. The bytes may still be gzip-compressed, may have been decompressed twice, or may have been truncated between a proxy and the application.
Browsers and HTTP libraries often decode Content-Encoding automatically. Debugging becomes confusing when logs show a compressed body at one hop and plain text at another without naming which layer performed the conversion.
Trace metadata and bytes at each hop
Record the response status, Content-Type, Content-Encoding, Content-Length or transfer framing, and the body representation available at the origin, proxy, client library, and application callback.
- Distinguish content compression from chunked transfer framing
- Check whether a proxy changed the body but preserved stale headers
- Confirm the client did not decompress an already decoded response
- Measure compressed and decompressed limits independently
Decode in the protocol-defined order
Let one HTTP-aware layer remove content codings, then parse the resulting bytes using the declared character encoding and finally parse JSON. Do not convert arbitrary compressed bytes to text or Base64 merely to silence a parser error.
If an upstream cache varies compression by request headers, confirm that its cache key includes the relevant Accept-Encoding behavior and that range or partial responses follow the platform contract.
A Flashman workflow
Use the JSON formatter only after decompression, Base64 to carry a synthetic compressed-byte fixture, hash to identify exact byte variants, and diff to compare decoded bodies or headers across hops.
Test compressed and uncompressed responses, empty bodies, truncation, stale headers, proxy recompression, decompression limits, and clients that enable or disable automatic decoding.