2026-07-10 · 6 min read · Rahul Chitturi
- json
- api
- debugging
Large numeric IDs can look fine in a JSON response and still be wrong by the time JavaScript reads them. Values above Number.MAX_SAFE_INTEGER may round silently, which turns customer IDs, order IDs, and database keys into near-matches that are painful to trace.
Start by separating the raw payload from the parsed value. If the wire response contains one number but the console, log line, or UI shows another, the bug is in parsing or serialization, not in the database row.
Compare the exact value at each boundary
Precision loss often hides behind formatting. Copy the raw response, the parsed object, and the value stored in logs or tickets, then compare them side by side. A one-digit difference at the end of an ID is enough to route a request to the wrong record.
- Check whether IDs are emitted as JSON numbers or strings
- Confirm JavaScript clients are not coercing strings back to Number
- Compare decimal and hexadecimal forms when infrastructure logs use mixed bases
- Record the timestamp and release that introduced the contract change
Prefer string contracts for identifiers
Identifiers are labels, not quantities. Treating them as strings preserves leading zeros, avoids rounding, and makes cross-language clients easier to reason about. If an API must keep numeric fields for compatibility, document the safe range and add fixtures around the boundary.
When fixing an existing contract, diff before and after payload examples so reviewers can see which fields changed type. Generated clients, analytics pipelines, and data exports may all need the same update.
A Flashman workflow
Use the JSON formatter to inspect raw payloads, the diff tool to compare parsed snapshots, and the number-base converter when logs or IDs appear in hexadecimal. Use the timestamp converter to align reports with the deploy that changed serialization.
Keep real customer IDs local. Replace values with synthetic IDs that are still larger than Number.MAX_SAFE_INTEGER so the reproduction proves the precision issue without exposing production data.