Guide
Unix Timestamps: Seconds vs Milliseconds
Timestamp bugs often come from mixing seconds and milliseconds. This guide explains how to spot and avoid them.
Related tools
The Unix epoch
Unix time counts elapsed time since 1970-01-01T00:00:00Z. The Z matters: the timestamp is based on UTC, not the local timezone of the machine displaying it.
Seconds versus milliseconds
Many APIs and token claims use Unix seconds. JavaScript Date values use milliseconds. A timestamp that is off by a factor of 1000 usually points to mixing these two units.
For example, JWT exp and iat claims are commonly seconds. Date.now() returns milliseconds. Passing Date.now() directly where seconds are expected creates dates far in the future.
UTC and local display
A timestamp represents one instant. UTC display is stable for logs, APIs, and cross-team debugging. Local display is useful when you need to compare that instant with what a person saw on their clock.
Common mistakes
- Treating JavaScript milliseconds as API seconds.
- Assuming a Unix timestamp stores a timezone.
- Comparing local formatted strings instead of numeric timestamps.
- Forgetting that some systems use milliseconds for logs and seconds for auth claims.
FAQ
How can I guess whether a timestamp is seconds or milliseconds?
Current Unix seconds are 10 digits, while current Unix milliseconds are 13 digits. Validation should still rely on API documentation when possible.
Does a Unix timestamp include timezone?
No. It represents an instant since the UTC epoch; timezone only affects display.