2026-07-23 · 5 min read · Rahul Chitturi
- json
- api
- debugging
A request can contain perfectly valid JSON and still fail because the transport contract is wrong. Missing Content-Type headers, unexpected charset values, or a proxy that rewrites headers can make one client work while another returns a generic 400.
Charset bugs are especially confusing when payloads include names, currency symbols, or localized strings. The bytes in the request body may not match what the server assumes, and logs often show the already-decoded text rather than the original evidence.
Separate JSON syntax from transport metadata
Start by saving a small, non-sensitive request fixture with method, URL, headers, and body together. Format the JSON first, then inspect the metadata that tells the server how to read those bytes.
- Confirm the header is application/json, optionally with charset=utf-8
- Check whether generated clients override or omit Content-Type
- Compare raw bytes for Unicode examples instead of relying only on rendered logs
- Look for gateways that normalize headers differently in staging and production
Build a safe reproduction
Use a minimal payload that preserves the failing characters and field names without exposing customer data. If the failure disappears after replacing text with ASCII-only placeholders, charset handling belongs near the top of the suspect list.
When the issue is a proxy or SDK default, diff the working and failing requests before changing server parsers. The contract should name both the JSON shape and the required transport headers.
A Flashman workflow
Use the JSON formatter to validate the body, the diff tool to compare request fixtures, and the URL encoder when the same payload also travels through query parameters or callback URLs.
Close the fix with a checklist: Content-Type, charset, generated client behavior, gateway behavior, Unicode fixture, and one regression test that keeps header and body together.