Milissegundos vs segundos: como converter millis em um timestamp Unix

Por que existem dois padrões

O tempo Unix foi originalmente definido em segundos — um inteiro parecia natural para um sistema que incrementava a cada tique do relógio. O objeto Date do JavaScript surgiu em 1995 e escolheu milissegundos para suportar a temporização de eventos abaixo de um segundo no navegador. Muitos bancos e linguagens de backend mantiveram os segundos Unix como padrão. Hoje, ambos os padrões coexistem em todo código que cruza a fronteira JavaScript-servidor, e por isso um valor pode parecer válido e ainda representar uma data a dezenas de milhares de anos.

Qual unidade cada linguagem usa

A forma mais segura de lembrar a divisão: as APIs Date do navegador geralmente querem milissegundos, as APIs de servidor no estilo Unix geralmente expõem segundos, e as bibliotecas de tempo mais novas costumam oferecer ambos. Não deduza a unidade só pela linguagem ao ler a documentação de uma API de terceiros; verifique a descrição do campo e os exemplos.

• Milliseconds: JavaScript Date.now(), Java System.currentTimeMillis(), Java Instant.toEpochMilli(), .NET ToUnixTimeMilliseconds()
• Seconds: Python time.time() (float), PHP time(), Go time.Now().Unix(), Ruby Time.now.to_i, C time(NULL), PostgreSQL EXTRACT(EPOCH)
• Both: Rust — duration.as_secs() for seconds, duration.as_millis() for milliseconds
• Python note: time.time() returns a float, so milliseconds are available as int(time.time() * 1000)

Detectar a unidade pelo valor

Uma heurística confiável para datas modernas: um número de 10 dígitos são segundos; um de 13 dígitos são milissegundos. Os segundos Unix atuais estão em torno de 1,7–2,1 bilhões (10 dígitos) e só chegarão a 13 dígitos no ano 33658. Os milissegundos Unix atuais já têm 13 dígitos. A heurística é mais forte de 2000 até alguns milhares de anos à frente; para datas históricas, negativas ou fixtures de teste compactas, use unidades explícitas em vez de adivinhar.

• valor de 10 dígitos → segundos (ex.: 1700000000 = 2023-11-14 UTC)
• valor de 13 dígitos → milissegundos (ex.: 1700000000000 = 2023-11-14 UTC)
• valor de 16 dígitos → microssegundos (divida por 1,000,000 para segundos)
• valor negativo → data anterior a 1 de janeiro de 1970 (segundos ou milissegundos)

Padrões de conversão seguros

A conversão em si é aritmética simples; o difícil é escolher onde ela deve acontecer. Converta no limite do sistema, nomeie o valor convertido e evite passar números brutos ambíguos por várias camadas.

• Seconds to milliseconds: seconds * 1000
• Milliseconds to whole seconds — JavaScript: Math.floor(ms / 1000)
• Milliseconds to whole seconds — Python: ms // 1000
• Milliseconds to whole seconds — Go: ms / 1000 (integer division)
• Universal guard in JavaScript: const toMs = ts => ts < 1e11 ? ts * 1000 : ts

Como os bugs de unidade aparecem em produção

Um bug de segundos-vs-milissegundos costuma sobreviver à validação porque ambos os valores são apenas números. Costuma aparecer depois como uma data impossível: janeiro de 1970 no JavaScript quando segundos foram tratados como milissegundos, ou um ano muito distante quando um backend tratou milissegundos como segundos.

• Data de 1970 na UI do JavaScript → segundos foram passados a new Date() sem multiplicar por 1000
• Ano 50000+ em Python, Go ou PHP → milissegundos foram passados a uma API que esperava segundos
• Tokens expirados que nunca expiram → timestamp de expiração salvo na unidade errada
• Entradas de cache que somem na hora → milissegundos divididos duas vezes ou segundos multiplicados duas vezes
• Gráficos de analytics com intervalos vazios → os limites da consulta usam unidade diferente dos timestamps de eventos salvos

Convenções de nomenclatura em APIs e bancos

Uma pequena convenção de nomenclatura evita a maioria desses bugs. Nunca publique um campo de API chamado timestamp a menos que a documentação seja excepcionalmente clara. Prefira nomes de campo que incluam o significado e a unidade.

• createdAtMs — Unix milliseconds, best for JavaScript clients
• createdAtSeconds — Unix seconds, common for backend services
• createdAtIso — ISO 8601 string, useful for human-readable API responses
• expiresAtUnixSeconds — explicit enough for auth tokens and signed URLs
• event_time TIMESTAMPTZ — native database time, with conversion handled by the database

FAQ milissegundos vs segundos

A tiny naming convention prevents most of these bugs. Never publish an API field called timestamp unless the documentation is unusually clear. Prefer field names that include both meaning and unit.

• createdAtMs — Unix milliseconds, best for JavaScript clients
• createdAtSeconds — Unix seconds, common for backend services
• createdAtIso — ISO 8601 string, useful for human-readable API responses
• expiresAtUnixSeconds — explicit enough for auth tokens and signed URLs
• event_time TIMESTAMPTZ — native database time, with conversion handled by the database

• Abrir o conversor de timestamp Unix
• Guia do JavaScript Date.now()
• 7 bugs de timestamp a evitar
• Milissegundos epoch para data
• Armazenar timestamps em bancos de dados

Microseconds (16 digits) and nanoseconds (19 digits)

Most production timestamps are seconds (10 digits) or milliseconds (13 digits), but two higher-precision formats also appear in real systems — microseconds and nanoseconds. The same digit-counting rule extends.

• 10 digits ≈ Unix seconds (~1.7×10⁹ today)
• 13 digits ≈ Unix milliseconds (~1.7×10¹²)
• 16 digits ≈ Unix microseconds (~1.7×10¹⁵) — Python time.time_ns()/1000, Postgres TIMESTAMP precision 6
• 19 digits ≈ Unix nanoseconds (~1.7×10¹⁸) — Java Instant.toEpochNano(), Go time.UnixNano(), Temporal.Instant.epochNanoseconds
• PostgreSQL to_timestamp() takes seconds with an optional fractional part; passing milliseconds yields a date around the year 55000
• Convert from any precision to milliseconds via integer arithmetic before doing further math
• Silent truncation: if a database column has millisecond precision but you store nanoseconds, the bottom 6 digits are dropped on insert

How many microseconds in a second? 1 second to milliseconds, microseconds to milliseconds

A quick reference for the unit math that drives every seconds/milliseconds/microseconds bug. The questions "how many microseconds in a second", "1 second to milliseconds", and "microseconds to milliseconds" are all powers of 1000 — but every order of magnitude is one place where production code goes wrong. Keep the table below within reach when writing high-resolution timestamp code.

• 1 second to milliseconds = 1,000 ms (10³)
• How many microseconds in a second? = 1,000,000 µs (10⁶)
• 1 second to nanoseconds = 1,000,000,000 ns (10⁹)
• Microseconds to milliseconds = µs ÷ 1,000 (10³ step down)
• Milliseconds to microseconds = ms × 1,000
• Nanoseconds to microseconds = ns ÷ 1,000
• Common precision: JavaScript Date.now() = ms, performance.now() = sub-ms float, Go time.UnixNano() = ns, Postgres TIMESTAMP precision 6 = µs
• Bug pattern: an API returns µs, code divides by 1000 once expecting seconds — actually got ms; result is 1000× off

Millisecond timer, time to ms, milliseconds to seconds conversion

Quick reference for the unit phrasings: "time to ms" (any time value scaled into milliseconds), "milliseconds to seconds conversion" (÷1000), and "millisecond timer" (a high-resolution timer for short intervals). For measuring elapsed time prefer a monotonic clock — wall-clock time can jump backwards on NTP correction or DST.

• Time to ms / time to milliseconds: seconds × 1000 = ms; microseconds ÷ 1000 = ms; nanoseconds ÷ 1,000,000 = ms
• Milliseconds to seconds conversion: ms ÷ 1000 = seconds; Math.floor(ms/1000) for integer seconds
• Millisecond timer (JavaScript): performance.now() returns sub-ms float since page load; Date.now() returns wall-clock ms
• Millisecond timer (Python): time.perf_counter() (monotonic float seconds); time.monotonic_ns() returns ns
• Millisecond timer (Java): System.nanoTime() for monotonic ns; Instant.now() for wall-clock ns precision
• Stopwatch rule: use monotonic clocks for elapsed time; wall-clock can jump backwards on NTP or DST