Dates and APIs
Unix timestamps, UTC, and local time without surprises
A debugging guide to seconds versus milliseconds, explicit offsets, daylight-saving transitions, and trustworthy date exchange.
An instant is not a display timezone
A Unix timestamp represents elapsed time from a defined epoch and identifies an instant independent of the viewer's timezone. Converting that instant to a calendar date requires a display zone. Two people can see different local dates for the same timestamp while still referring to the same moment.
Use UTC for machine exchange and logs unless a contract explicitly requires another representation. Include a Z suffix or numeric offset in date strings. A date and time without an offset may be interpreted as local time, and different environments can apply different zones or parsing rules.
Seconds and milliseconds are the classic integration error
Unix timestamps are frequently expressed in seconds, while JavaScript Date values commonly use milliseconds. The values differ by a factor of one thousand. A seconds value treated as milliseconds points near 1970; a milliseconds value treated as seconds may be far outside a usable date range.
Do not rely only on magnitude heuristics in a production API. Document the unit in the field name or schema, validate its allowed range, and include an example. During debugging, compare both interpretations and confirm the intended date with the producing system.
Daylight-saving rules belong to named zones
A fixed offset such as -05:00 describes one relationship to UTC at one instant. It does not contain the historical and future daylight-saving rules associated with a region such as America/New_York. Recurring local schedules therefore need a named timezone and a policy for skipped or repeated wall-clock times.
Historical timezone rules can change when governments update policy, and devices may ship different timezone database versions. Test transitions explicitly when payroll, billing, transportation, or scheduled jobs depend on local civil time.
Create reproducible date reports
When sharing a timestamp issue, record the raw value, unit, UTC ISO result, intended named timezone, observed local output, browser or runtime, and device timezone setting. This lets another person reproduce the conversion instead of guessing from a screenshot.
Avoid ambiguous strings such as 07/08/26. Prefer an ISO-style date with four-digit year and explicit offset when an instant is intended. For date-only concepts such as a birthday, do not invent midnight UTC unless the data model genuinely needs an instant.