Unix timestamps, time zones and conversion mistakes
A Unix timestamp identifies an instant relative to 1970-01-01 00:00:00 UTC. It does not contain a local time zone.
Seconds or milliseconds?
Traditional Unix time counts seconds. Many JavaScript APIs count milliseconds, producing values roughly one thousand times larger. A modern seconds value is typically ten digits, while milliseconds commonly use thirteen, but digit count is only a diagnostic clue. Confirm the source contract. Interpreting seconds as milliseconds produces a date near January 1970; interpreting milliseconds as seconds produces an invalid or extremely distant date.
An instant is not a wall-clock label
The timestamp represents the same instant worldwide. Converting it to “2026-07-19 15:00” requires a time zone, whose rules determine the local offset. Storing only a local date and time loses information during daylight-saving transitions, when a clock time can occur twice or not occur at all. For events, store an instant and display it in the viewer's chosen zone. For an appointment tied to local civil time, also preserve the zone identifier because future offset rules can change.
UTC, offsets and time-zone IDs
“UTC” has no seasonal offset. A numeric offset such as +03:00 says how local time related to UTC
at one instant, but does not describe historical or future rules. A zone ID such as Europe/Istanbul refers to
a rule set. Do not label a local timestamp with Z; that suffix explicitly means UTC and silently
changes the represented instant if the value was local.
Negative, fractional and very large values
Negative timestamps refer to instants before the Unix epoch when supported. Fractions can represent sub-second precision, although an API may require an integer. Very large millisecond values can lose integer precision in environments that store all numbers as floating point. Define unit, accepted range and precision at API boundaries rather than guessing from the value.
Common application failures
- Multiplying milliseconds by 1,000 again before constructing a date.
- Parsing a date without a zone and allowing the server's local configuration to decide.
- Formatting logs only in local time, making events from multiple regions difficult to order.
- Using a 32-bit signed integer for seconds beyond its supported 2038 range.
- Comparing formatted strings rather than normalized instants.
Recommended workflow
- Document the unit and whether fractions are accepted.
- Parse to a time-aware instant using a maintained date library.
- Keep UTC for interchange and logs; convert only for display or civil-time rules.
- Show the zone or offset next to any displayed time.
- Test dates around midnight, leap days and any daylight-saving transitions relevant to users.