Unix time represents an instant as a count from a shared origin: the beginning of 1970 in UTC. That simple idea lets unrelated systems compare, store, and transmit time without carrying a calendar format in every value. A timestamp can sort events, expire tokens, schedule jobs, and measure durations. Yet the apparent simplicity hides questions about units, clock accuracy, leap seconds, range, and the difference between an instant and a local human time.
An instant is not a formatted date
A Unix timestamp identifies a position on a timeline. It does not contain a timezone, language, month name, or display format. Software converts the instant into a local calendar representation when presenting it to a person. The same timestamp may appear as Tuesday evening in one location and Wednesday morning in another.
This separation is useful. Systems can store one unambiguous instant and display it according to each user's locale. Problems begin when a local wall-clock value is mistakenly treated as though it already identified a global instant.
Seconds and milliseconds are easy to confuse
Traditional Unix timestamps count seconds, while JavaScript and many APIs commonly use milliseconds. The values differ by a factor of one thousand. Interpreting milliseconds as seconds produces a date far in the future; interpreting seconds as milliseconds produces a date near the beginning of 1970.
Field names and schemas should make units explicit. Names such as created_at_ms or documented ISO strings are clearer than an unexplained integer. Heuristics based on digit count help debugging but should not define a production contract.
Computer clocks are measurements
A timestamp usually comes from a machine clock, and machine clocks can be wrong. They drift, synchronize over networks, jump after correction, and may differ between servers. Wall clocks are suitable for recording approximate real-world instants, but they are risky for measuring elapsed time because adjustment can make time appear to move backward or forward.
Programs should use a monotonic clock for durations, retries, and timeout calculations. A monotonic clock advances consistently but has no meaningful calendar date. Wall time and elapsed time are different concepts and deserve different APIs.
Leap seconds complicate the ideal timeline
Earth's rotation is not perfectly regular, so civil time has occasionally inserted leap seconds. Unix time implementations generally do not represent leap seconds as a distinct, universally agreed timestamp. Systems may repeat a second, smear an adjustment over time, or follow platform-specific behavior.
Most business applications can rely on ordinary platform handling, but scientific, financial, and distributed systems with strict timing requirements need to understand their clock source and synchronization policy. “UTC” does not remove every implementation detail.
Range and precision have practical limits
Older systems using signed 32-bit seconds encounter the year 2038 limit. Modern 64-bit representations extend far beyond practical needs, but databases, file formats, and external APIs may still impose narrower ranges. Floating-point timestamps can also lose sub-second precision for large values.
Choose representations based on required range and precision. Nanosecond values may be useful in tracing systems but misleading when the source clock cannot measure that accurately. More digits do not automatically mean better truth.
Store instants when events actually happen
Creation times, log entries, transaction events, and token expirations are instants and fit UTC timestamps well. Recurring human schedules are different. “Every day at 9:00 in Kyiv” is a rule tied to a timezone and daylight-saving changes, not one fixed offset or timestamp.
Model the user's intent. Store an instant for a one-time meeting after resolving its timezone. Store local time, recurrence rules, and an IANA timezone for future recurring events that must follow local clock changes.
Database types encode assumptions
Databases offer several date and timestamp types with different timezone and range behavior. Some normalize values to UTC; others store a wall-clock value without zone context. Choosing a type without understanding those rules can silently reinterpret data during reads, writes, or server migrations.
Document whether a column stores an instant, local date, or local date-time. Application and database session timezones should be configured deliberately rather than inherited from whichever machine runs the query.
Conversion should preserve meaning
When converting timestamps, first identify the unit and whether the value represents an instant. Then display it with an explicit timezone and an unambiguous format such as ISO 8601 for technical exchange. Human interfaces can add localized forms, but logs and APIs should avoid ambiguous numeric dates.
Include representative examples in API documentation, especially around sub-second precision and offsets. A single sample often exposes a unit or timezone assumption more clearly than a general statement that a field is a timestamp.
A Unix timestamp is a durable common denominator, not a complete model of time. Used for genuine instants with explicit units and sensible clock assumptions, it provides a simple bridge between systems. Used as a replacement for every calendar concept, it creates errors that surface only when timezones, schedules, or clock corrections matter.