Guide
Why API Dates and Unix Timestamps Don’t Always Match
Learn a fast workflow to explain why API date strings and Unix timestamps can represent different moments.
An API can return a readable date field and a Unix timestamp field that look related but still disagree. Most mismatches come from timezone conversion rules, rounding, or different source fields.
Understand that fields may have different origins
APIs often include both an event timestamp and a display-ready date.
Those values can be generated at different pipeline steps and are not always exact mirrors.
Check whether the Unix value is seconds or milliseconds
Unit mismatch is still the fastest way to create a fake disagreement.
Confirm digit length before comparing with readable date output.
Verify timezone handling on both fields
A date string may include offset information while a Unix timestamp is timezone-neutral.
If one field was formatted in local server time, differences can appear immediately.
- Look for Z, +09:00, -05:00 style suffixes.
- Confirm whether backend formatting uses UTC or local timezone.
- Test conversion in UTC and local views.
Watch for rounding and truncation behavior
Some APIs round to seconds while others preserve milliseconds.
Small truncation differences can become visible in sorted tables and incident timelines.
Use one known sample to validate assumptions
Pick a record with a known real event time and compare every field from storage to UI.
This quickly shows whether mismatch comes from API generation or frontend rendering.
Use this guide when
- Two date fields in one API response disagree.
- Backend logs and dashboard time labels do not align.
- You need to explain a time mismatch to teammates quickly.
- A timestamp seems correct but the rendered date looks shifted.
Compare source, unit, and timezone together
Treat each date field as separate data until you confirm origin, unit, and timezone assumptions.