Unix timestamp seconds vs milliseconds describes a unit difference: the millisecond value is 1,000 times the seconds value for the same instant. A receiver that assumes the wrong unit can produce a plausible but incorrect date.
Use the FindUtils Unix Timestamp Converter to inspect a known example. Then record the expected unit at the boundary between the producer and receiver. A conversion tool cannot recover an undocumented intention from a bare number.
Why can a valid number produce the wrong date?
A number can pass syntax checks while carrying the wrong meaning. The JSON field "created_at": 1788912000 does not declare an epoch, a unit, or a precision rule.
Suppose one application writes that value as Unix seconds. A second application passes it directly to JavaScript Date, which expects milliseconds. Both programs accept the number. The second program displays January 21, 1970, at 16:55:12 UTC.
The expected event was September 9, 2026, at midnight UTC. The problem occurs before date formatting: the receiving application assigned the wrong unit.
The MDN Date reference documents the constructor's millisecond representation. The examples here use synthetic values and direct calculations. They do not describe a customer incident.
Three separate checks help explain a date error:
- Unit: Did the receiver interpret seconds as milliseconds, or the reverse?
- Offset: Did a date string identify UTC or an explicit local offset?
- Precision: Did an intermediate step remove fractional seconds?
Check these properties before you change the display format. A new display format can make the same incorrect instant easier to read.
What does the same instant look like in each format?
September 9, 2026, at midnight UTC has several equivalent representations. The values below agree because each row declares its representation.
| Representation | Example | Information the receiver still needs |
|---|---|---|
| Unix seconds | 1788912000 | Epoch, seconds unit, accepted range |
| Unix milliseconds | 1788912000000 | Epoch, milliseconds unit, accepted range |
| UTC date-time string | 2026-09-09T00:00:00Z | Accepted syntax and precision |
| Date-time with offset | 2026-09-09T03:00:00+03:00 | Accepted syntax and precision |
A numeric offset describes the relationship between the written clock time and UTC. In this example, subtracting three hours from 03:00:00+03:00 gives midnight UTC. RFC 3339, section 4.2 defines the offset direction.
Choose one representation for each field. If two interfaces need different representations, document the conversion between them. Avoid a field that sometimes contains seconds and sometimes contains milliseconds.
The JSON Formatter can make an example response easier to inspect. It cannot infer which unit an undocumented timestamp field intends.
How do you find the incorrect conversion?
Trace one known value from its source to its final use. Record the unit at each step. Stop at the first boundary where the documented meaning changes unexpectedly.
Step 1: Select a known event
Choose a synthetic event with an independently known UTC time. Open the Unix Timestamp Converter for a reference check. Keep the original field value beside the expected date.
Step 2: Read the producer contract
Confirm the field name, epoch, and unit in the producer documentation or code. Do not use a successful parse as a substitute for this information. If the unit is absent, record that gap before changing the receiver.
Step 3: Identify the receiving operation
Check the actual function that consumes the value. A JSON number has no unit. A JavaScript Date constructor, a programmatic converter, and a browser form can each use different rules.
Step 4: Inspect intermediate calculations
Look for multiplication, division, rounding, and string conversion. Mark each operation with its input and output unit. Two separate multiplications by 1,000 are a useful place to investigate when the result is far in the future.
Step 5: Compare the expected instant
Convert the final value into a qualified UTC string. Compare that string with the synthetic reference. Keep the raw source value available so that a display change cannot hide the original mismatch.
This procedure identifies a conversion boundary. It does not validate clock synchronization, delayed delivery, or the truth of an event reported by another system.
Which three examples expose different errors?
The following cases isolate unit conversion, precision loss, and an incorrect offset label. Use separate examples because one successful modern timestamp does not exercise all three conditions.
Example 1: Seconds reach a milliseconds input
Pass the same seconds value through two calculations:
const eventSeconds = 1788912000; new Date(eventSeconds).toISOString(); // 1970-01-21T16:55:12.000Z new Date(eventSeconds * 1000).toISOString(); // 2026-09-09T00:00:00.000Z
The multiplication belongs in the second expression because eventSeconds declares the source unit. If the source already provides milliseconds, use that value directly. Do not add another multiplication to compensate for a display problem.
Example 2: Whole seconds remove precision
Suppose a source records an event 123 milliseconds after midnight:
const originalMs = 1788912000123; const wholeSeconds = Math.floor(originalMs / 1000); const restoredMs = wholeSeconds * 1000; const lostMs = originalMs - restoredMs; // wholeSeconds: 1788912000 // restoredMs: 1788912000000 // lostMs: 123
This conversion can be acceptable when the destination requires whole seconds. It is unsuitable when the application must preserve the original millisecond value.
For example, two synthetic events at .123Z and .900Z map to the same whole second. A whole-second field cannot distinguish their original fractional times. Preserve the original precision or add a separate ordering field when that distinction matters.
Example 3: A local clock time receives the wrong suffix
Compare these two strings:
2026-09-09T03:00:00+03:00 2026-09-09T03:00:00Z
The first identifies midnight UTC. The second identifies 03:00:00 UTC, three hours later. Replacing an offset with Z without changing the clock time changes the instant.
Convert the instant before you change its label. If the source has no offset at all, obtain the missing context. JavaScript treats a standard date-and-time string without an offset as local time. See the Date.parse reference.
What belongs in a timestamp contract?
A timestamp contract names the representation and the accepted behavior. The table below is an example policy for a new event field. It is not a description of every FindUtils input or a universal API standard.
| Contract item | Example decision | Reason |
|---|---|---|
| Field name | occurred_at_ms | Makes the unit visible during review |
| Epoch | Unix epoch | Establishes the origin |
| Unit | Integer milliseconds | Removes unit guessing |
| Meaning | Reported event instant | Separates event time from receipt time |
| Precision | Preserve milliseconds | States what a conversion must retain |
| Missing value | null means unknown | Keeps zero available for the epoch |
| Accepted range | Define bounds for the product | Rejects values outside the intended domain |
| Display | UTC for logs; explicit zone for readers | Separates storage from presentation |
| Error behavior | Reject malformed or ambiguous input | Prevents partial parsing from appearing successful |
Include at least one valid example with its expected UTC string. Add a boundary example and an invalid example. A reviewer should be able to explain why each value passes or fails without guessing from its length.
Record event time and receipt time in separate fields when both matter. A delayed message can have an earlier event time than its arrival time. Renaming both values timestamp hides that distinction.
What should you check in the FindUtils converter?
The browser and programmatic versions use different input rules. The browser guesses milliseconds when the raw input exceeds 10 characters. The REST converter uses seconds in to_date mode.
This distinction matters when you move a manual example into an automated request. Do not assume that a millisecond number accepted in the browser is valid for the API's seconds input.
Use the Unix Timestamp Converter guide for the complete browser instructions and limitations. It also explains the local date form and the need to enter both date fields.
The browser computes the entered date values locally. Read the Privacy Policy for website data practices. For a support example, remove unrelated private fields and use synthetic event data.
Which shortcuts cause repeated mistakes?
The most useful shortcuts preserve meaning. Shortcuts that infer meaning from appearance can repeat the same error in several systems.
Mistake 1: Using digit count as the contract
A short value can represent historical milliseconds. A long value can represent later seconds. Raw length can also include a sign or whitespace. Use a declared unit at application boundaries.
Mistake 2: Rounding before the requirement is clear
Confirm the destination precision before dividing a millisecond value. If the destination needs whole seconds, state how to round. Keep the original when later operations require more precision.
Mistake 3: Treating a timestamp as a recurring schedule
A timestamp identifies an instant. It does not specify a repeating local appointment. Store the schedule rule and its intended zone separately. Use the Cron Expression Generator guide for that different task.
Mistake 4: Assuming a converter validates the whole field
Some parsers accept a numeric prefix and ignore later characters. Require validation for the complete input in the receiving application. Conversion output alone is insufficient evidence.
Tools used in this article
These tools help inspect a representation before you update a data contract:
- Unix Timestamp Converter: Compare an epoch value with a readable date.
- JSON Formatter: Inspect a synthetic event payload.
- Timezone Converter: Compare the same time across named zones.
FAQ
Q1: Are Unix timestamps always in seconds? A: Unix time conventionally uses seconds. APIs also use Unix milliseconds and other resolutions. Read the field's contract before converting its value.
Q2: Why does JavaScript show 1970 for a recent event? A: A seconds value may have reached a milliseconds input. Check the producer unit before applying multiplication by 1,000.
Q3: Should an API use integers or date strings? A: Either can work with a clear contract. Integers need an explicit epoch and unit. Date strings need an accepted syntax, offset rule, and precision rule.
Q4: Can a UTC offset identify a time zone? A: An offset states a difference from UTC for the represented time. It does not supply a named region's future clock-change rules.
Q5: Can I recover milliseconds after conversion to whole seconds? A: No. The whole-second result does not retain the removed fraction. Keep the original value when that precision is required.
Next steps
Apply the contract table to one timestamp field in your application. Confirm its example value with the converter guide.
Read the Timezone Converter guide for cross-region display. Use the configuration conversion review checklist when timestamps form part of a larger import.