Segundos vs milissegundos

Unix time é definido em segundos, mas muitos runtimes expõem milissegundos para precisão maior. Misturar os dois é um dos bugs de timestamp mais comuns.

Heurística pelo número de dígitos

Regra prática em decimal:

Dígitos	Em geral significa	Exemplo
10	Segundos	1700000000
13	Milissegundos	1700000000000

Outros comprimentos precisam de contexto — confirme sempre na documentação da API.

Por que os dois existem

• Segundos — compacto, suficiente para muitos logs e expiração JWT; usado por time.time() em Python, várias APIs C e date +%s no Linux
• Milissegundos — Date.now() em JavaScript, System.currentTimeMillis() em Java, algumas APIs JSON para ordenação sub-segundo

Converter entre eles é multiplicar ou dividir por 1000 — na direção errada, datas pulam para 1970 ou para o futuro distante.

Segundos fracionários

Alguns sistemas retornam segundos em ponto flutuante (1700000000.123). Ainda é “segundos + fração”, não milissegundos. Interpretar como campo inteiro em ms perde precisão ou falha na validação.

Hábitos defensivos

1. Leia o schema da API ou um payload de exemplo primeiro
2. Se a data parecer errada por ~1000×, troque a unidade mentalmente
3. Armazene internamente em uma convenção (muitas vezes ms ou µs no app) e converta nas fronteiras
4. Em bancos, prefira tipos TIMESTAMPTZ quando disponíveis em vez de inteiros “soltos”

Resumo

Segundos e milissegundos nomeiam a mesma linha do tempo em escalas diferentes. Saiba qual escala sua fonte usa antes de converter ou comparar.