2026-08-29 · 6 min read · Rahul Chitturi
- time
- api
- debugging
A timestamp can change its displayed clock time without changing the instant it represents. Problems begin when one layer treats a local wall time as UTC, drops an offset, truncates precision, or serializes seconds where another layer expects milliseconds.
The visible symptom is often an event shifted by several hours or sorted into the wrong day even though every parser accepted the value.
Identify the time concept first
Decide whether the field represents an instant, a local appointment, or a calendar date. An instant can be normalized to UTC; a future local appointment may also need an IANA time zone because regional offset rules can change.
- Require Z or an explicit offset for API instants
- Keep date-only fields out of timestamp parsers
- Distinguish epoch seconds from epoch milliseconds
- Record the precision supported by every storage layer
Trace one value through every boundary
Capture the original string, parsed epoch value, database representation, API output, and browser display for one synthetic fixture. Compare instants numerically before comparing formatted strings.
Avoid fixing a display bug by adding a constant hour offset. That workaround fails across users, regions, and daylight-saving transitions.
A Flashman workflow
Use the timestamp converter to compare epoch and ISO forms, the JSON formatter to inspect quotes and numeric units, the diff tool to trace serialization changes, and the URL tool when timestamps travel in query parameters.
Add round-trip tests around offset boundaries, fractional seconds, date changes, and the exact database driver used in production.