Dev · 3 min de leitura ·
Timestamps Unix: segundos ou milissegundos?
O bug dos 13 dígitos que vai para produção toda semana, e uma regra bem simples para diferenciar as duas unidades.
O JavaScript fala em milissegundos. A maioria dos back-ends fala em segundos. Misture os dois e suas datas vão parar em janeiro de 1970, ou dezenas de milhares de anos no futuro.
Conte os dígitos
Um timestamp atual em segundos tem 10 dígitos (1790000000 é 21 de setembro de 2026). O mesmo instante em milissegundos tem 13 dígitos; em microssegundos, 16, e em nanossegundos, 19.
A regra
Se o valor absoluto for maior que 10¹², são milissegundos; caso contrário, trate como segundos. Vale para qualquer timestamp em milissegundos depois de setembro de 2001 e qualquer timestamp em segundos antes do ano 33658.
const ms = Math.abs(n) > 1e12 ? n : n * 1000;Um timestamp não tem fuso horário
Um timestamp Unix conta os segundos desde 1º de janeiro de 1970 às 00:00 UTC. O mesmo número é o mesmo instante no mundo inteiro; só muda a forma de exibir. Os bugs aparecem quando o horário local é convertido em timestamp como se fosse UTC, o que desloca todas as datas pela diferença do seu fuso, muitas vezes uma ou duas horas, e de novo nas mudanças de horário de verão. Guarde e envie timestamps em UTC e converta para o horário local só ao mostrá-los a uma pessoa.
Obtendo a hora atual em linguagens comuns
JavaScript Date.now() milissegundos
JavaScript Math.floor(Date.now() / 1000) segundos
Python time.time() segundos (com fração)
Java System.currentTimeMillis() milissegundos
Go time.Now().Unix() segundos
PostgreSQL EXTRACT(EPOCH FROM now()) segundos
MySQL UNIX_TIMESTAMP() segundosDatas antes de 1970 e o ano 2038
Timestamps negativos são válidos: −86400 é 31 de dezembro de 1969. Alguns sistemas antigos e planilhas não lidam com eles, por isso datas de nascimento e dados históricos são uma fonte comum de bugs. Na outra ponta, um inteiro de 32 bits com sinal acaba em 2147483647, que corresponde a 03:14:07 UTC de 19 de janeiro de 2038. Sistemas que ainda guardam timestamps em 32 bits vão voltar para 1901; o armazenamento em 64 bits evita o problema por bilhões de anos.
Segundos intercalares
O tempo Unix ignora os segundos intercalares: todo dia tem exatamente 86.400 segundos. Isso mantém a aritmética simples e, em quase toda aplicação, a diferença não importa. Só sistemas que precisam de intervalos precisos atravessando um segundo intercalar, como alguns científicos ou financeiros, precisam se preocupar.
Checklist rápido de depuração
- A data cai em janeiro de 1970: um valor em segundos foi lido como milissegundos.
- O ano tem cinco dígitos: um valor em milissegundos foi lido como segundos.
- Todas as datas estão erradas pelo mesmo número de horas: o horário local foi tratado como UTC, ou o contrário.
- As datas erram em uma hora em parte do ano: uma mudança de horário de verão foi ignorada.
- As datas pulam para 1901: um estouro de 32 bits.
Escolha a unidade explicitamente
O conversor de timestamps da 4Dev não tenta adivinhar: "Unix Timestamp" significa segundos e "Unix Timestamp (ms)" significa milissegundos, ao lado de variantes em microssegundos e nanossegundos: 33 formatos no total, incluindo ISO 8601, RFC 2822, SQL DATETIME e datas seriais do Excel.
ISO 8601 quando pessoas leem a data
Timestamps são ótimos para guardar e calcular, mas difíceis de ler. Em logs, APIs e arquivos que pessoas abrem, o ISO 8601, como 2026-09-21T14:30:00Z, não é ambíguo, ordena corretamente como texto e informa o fuso horário de forma explícita. Converter entre os dois é exatamente para o que serve o conversor de timestamps.