TL;DR: Most “wrong timestamp” bugs are unit mistakes—seconds versus milliseconds—or time zone display issues, not a broken backend. Convert the raw epoch with a trusted browser tool, compare to UTC, then inspect offsets.
Epochs look like large integers until they are not
Unix time counts seconds since 1970-01-01 UTC. JavaScript’s Date.now() counts milliseconds. A 13-digit value fed into a function that expects 10 digits lands in the far future; a 10-digit value treated as milliseconds collapses into January 1970. Support threads fill with screenshots of “the API returned year 58000” that were really unit mismatches.
Read the contract before converting
Check the API docs for unit and time zone. Phrases like “Unix timestamp,” “epoch millis,” and “UTC ISO-8601” are not interchangeable. If the field is a string with Z, you may not need epoch conversion at all—parse ISO first. If the field is numeric, count the digits:
- ~10 digits: likely seconds.
- ~13 digits: likely milliseconds.
- ~16 digits: sometimes microseconds—confirm before dividing.
- Negative: pre-1970; still valid in many systems.
Display time zone is not storage time zone
Databases often store UTC. Dashboards may show local time. A converter that prints your browser’s local zone can look “wrong” compared to a colleague in another country even when both match the same instant. Always compare against an explicit UTC rendering before filing a bug.
A debugging sequence that saves an afternoon
Copy the raw integer from logs—not from a UI that may have already formatted it. Convert to UTC human time. Ask: does this match the business event (order placed, job started) within expected latency? If the UTC time is right but the app screen is wrong, the bug is in formatting or default zone, not ingestion.
If UTC is wrong by a factor of 1000, switch units. If it is wrong by several hours with clean units, look for double offsets (apply local offset twice) or for servers still set to a regional zone while pretending to be UTC.
DST and “every day at 2 a.m.” jobs
Cron-like schedules defined in local time misbehave across daylight saving transitions: times can skip or repeat. Epoch math in UTC avoids that class of error for machine intervals. When product requirements insist on wall-clock local time, store the zone ID (e.g., America/Chicago) beside the rule—not only a numeric offset, which changes.
Converters help verify a single instant; they do not replace proper zone libraries in code. Use the tool to validate examples in tickets, then fix the library usage in the repo.
Leap seconds and purity fantasies
Most business apps can ignore leap seconds; Unix time as commonly implemented smears or ignores them. If you are not writing satellite ground software, do not blame leap seconds first. Blame units, zones, and clock skew between hosts. NTP drift of a few seconds still explains more outages than exotic calendar theory.
Keep fixtures readable
In tests, prefer ISO-8601 strings for human-reviewed fixtures and convert to epoch only at the boundary under test. When you must assert on an integer, comment the UTC meaning beside it. Future readers should not need to decode 1714521600 in their head.
Clock skew between laptop, container, and API
Signed requests and JWT expiry claims fail when the local clock is minutes off. Before blaming the server for an invalid signature, convert the server’s date header and your local epoch to UTC side by side. VMs that pause while a laptop sleeps often wake with stale clocks until NTP catches up.
Containers inherit time from the host, but some Windows and Docker combinations still surprise developers after daylight-saving changes. If your JWT is not yet valid, check the nbf claim and whether you accidentally issued tokens in milliseconds while the verifier expects seconds—another unit bug that looks like skew.
Log both human UTC and raw epoch in staging. Support engineers should not have to decode integers under pressure. When filing bugs, include the raw value, the unit you believe it uses, and the UTC string from a converter so responders share one interpretation.
Batch jobs that bucket events by local calendar day need explicit zone IDs. Bucketing by epoch intervals of 86400 seconds drifts around DST. Converters help explain a single mis-bucketed row; fixing the bucket function requires zone-aware libraries in code.
Keep a short cheat sheet near your desk: ten digits suggest seconds, thirteen suggest milliseconds, and ISO-8601 strings with a trailing Z are already UTC. That sheet prevents the most common support ping-pong when on-call engineers are tired. When in doubt, convert once to UTC, write the human time in the ticket, and only then discuss business logic. Tools exist so you do not do epoch math in your head during an incident.
Next time a timestamp looks absurd, convert the raw epoch to UTC with a dedicated utility on www.masters-tool.com before rewriting half the client. Most API “time bugs” shrink to a single wrong unit or a local clock display.
