DATE DEBUGGING GUIDE · 7 MIN READ

Unix timestamps: seconds, milliseconds and time zones

A Unix timestamp counts time from the Unix epoch, but APIs disagree about whether the unit is seconds or milliseconds. A three-digit mistake can move a date thousands of years or close to 1970.

Identify the unit

Current Unix seconds are commonly 10 digits; milliseconds are commonly 13. Digit length is a useful clue, not a permanent rule. Read the API contract and compare the result with the expected date range.

Separate an instant from its display zone

The timestamp represents an instant. ISO UTC, UTC text and device-local time can display different clock values and even different calendar dates without representing different moments.

Check rounding and precision

Converting milliseconds to seconds discards sub-second precision unless the remainder is preserved. Negative timestamps represent instants before 1970 and may not be accepted by every system.

Worked example

1710000000 seconds and 1710000000000 milliseconds represent the same instant. Treating the latter as seconds produces an invalidly distant date.

Limitations to review

• Local output depends on the device time zone.
• A numeric value alone may not state its unit.
• Calendar-only dates should not be guessed as midnight UTC.