What a Unix Timestamp Actually Is
A Unix timestamp is simply the number of seconds that have elapsed since midnight UTC on January 1, 1970 — a moment programmers call "the epoch." Instead of storing a date as a year, month, day, hour, minute, and second, most systems internally store it as a single, ever-increasing integer, which makes comparing, sorting, and doing arithmetic on dates enormously simpler. A timestamp like 1700000000 represents a specific, unambiguous instant in time regardless of what timezone the server or the viewer happens to be in.
The Seconds-vs-Milliseconds Trap
The single most common bug involving Unix timestamps isn't a calendar bug at all — it's a units bug. Traditional Unix time is measured in whole seconds, but JavaScript's Date.now() and many modern APIs return timestamps in milliseconds instead, for finer precision. Mixing the two up produces dates that are wildly wrong — usually landing somewhere in 1970, because a millisecond value treated as seconds represents a point in time roughly 1,000 times closer to the epoch than intended.
Fortunately, there's a reliable heuristic for telling them apart: a timestamp in seconds for any date between roughly 2001 and 2286 will have exactly 10 digits, while the equivalent value in milliseconds will have 13 digits. Counting digits is a fast, dependable way to auto-detect which unit you're dealing with before doing any conversion — and it's exactly what a well-built timestamp tool should do automatically rather than asking the user to specify.
Reading a Timestamp in Multiple Formats
Once you know a timestamp's unit, converting it to a readable date is straightforward — but which readable format you need depends on context:
- UTC: The timezone-independent representation. Always use this when comparing timestamps across systems or logging events from servers in different regions, since it removes any ambiguity about which timezone was intended.
- Local time: Whatever timezone the viewer's device is currently set to. Useful for displaying times to end users in a way they intuitively understand, but not reliable for machine-to-machine comparison since it changes based on the viewer's location and daylight saving rules.
- ISO 8601: The standardized, machine-parseable format like
2024-03-15T10:30:00.000Z, used almost universally in APIs, log files, and database exports because every major programming language can parse it unambiguously. - RFC 2822: An older, more verbose format like
Fri, 15 Mar 2024 10:30:00 GMT, still commonly seen in email headers and some legacy HTTP contexts.
Converting the Other Direction: Date to Timestamp
The reverse conversion — picking a specific date and time and getting its Unix timestamp — is just as commonly needed, especially when constructing API query parameters that expect a timestamp range, or when scheduling something for a specific future moment. The key detail to get right here is timezone handling: a date and time typed by a user is implicitly in their local timezone unless explicitly marked otherwise, so the conversion needs to account for the viewer's UTC offset before producing the final timestamp — otherwise the resulting instant will be off by however many hours separate the user's timezone from UTC.
Why This Still Trips Up Experienced Developers
Even seasoned engineers occasionally ship a units bug, because the failure mode is silent rather than a thrown error — dividing or multiplying by 1000 in the wrong direction produces a technically valid date, just an absurdly wrong one (frequently a date near January 1, 1970, or a date thousands of years in the future). Automated tests that check "is this a valid Date object" won't catch it; only tests that check the actual value will. This is exactly why a dedicated converter tool that shows the detected unit explicitly, alongside multiple output formats, is so useful for quickly sanity-checking a suspicious timestamp during debugging.
A Quick Mental Model to Keep
Whenever you encounter an unfamiliar timestamp, count its digits before doing anything else: 10 digits means seconds, 13 means milliseconds, and anything else is worth double-checking rather than assuming. Combined with always normalizing to UTC internally and only converting to local time for display, this simple habit eliminates the majority of timestamp-related bugs before they ever reach production.