2026-07-12 · 5 min read · Rahul Chitturi
- timestamps
- api
- debugging
Timestamp bugs often look like timezone bugs until you notice the year is impossible. APIs that mix Unix seconds, Unix milliseconds, and ISO strings can schedule work decades away, expire sessions immediately, or hide incident events outside the searched window.
Before changing timezone settings, identify the unit at every boundary: database storage, API payload, JavaScript Date construction, scheduler input, logs, and analytics export.
Name the unit in examples
Ten-digit epoch values are usually seconds. Thirteen-digit values are usually milliseconds. That shortcut is helpful, but the contract should still say createdAtSeconds, expiresAtMs, or an ISO field name that removes guesswork.
- Convert sample values to human dates before triage
- Check whether JavaScript Date received seconds without multiplying by 1000
- Compare scheduler run times with API-created timestamps
- Diff before/after JSON examples when changing field units
Keep timezone and unit bugs separate
A timestamp can be the right instant in the wrong display timezone, or the wrong instant because the unit was converted twice. Write down both the raw value and the interpreted ISO date so reviewers can see which problem they are fixing.
If a cron job consumed the timestamp, preview the next runs around the incident. A seconds/milliseconds bug can combine with scheduler timezone assumptions and make the visible symptom move by both hours and years.
A Flashman workflow
Use the timestamp converter for raw values, the JSON formatter to inspect payload fields, the cron parser to preview schedule behavior, and the diff tool to compare contract examples before and after the fix.
Keep sanitized but realistic values in regression tests. Include one seconds value, one milliseconds value, and one ISO string so future clients cannot silently reintroduce the ambiguity.