Los siete errores que producen una fecha equivocada
Un conversor epoch hace aritmética sencilla, así que cuando la salida está mal la causa casi nunca es la matemática — es la entrada. Un timestamp no lleva etiqueta que diga si está en segundos o milisegundos, en UTC o local, ni qué precisión tiene, y toda conversión errónea viene de adivinar mal uno de esos puntos. La pista más rápida es el año resultante: una fecha cerca de 1970 o a miles de años en el futuro es una confusión de unidad, y una fecha correcta pero desfasada un número redondo de horas es un error de zona. La tabla siguiente es la guía de campo; las secciones posteriores explican a fondo los errores de unidad y de zona y muestran cómo verificar una conversión en el código.
| Error | Lo que ves | Causa | Solución |
|---|---|---|---|
| Segundos leídos como milisegundos | La fecha cae en 1970 | Date y Date.now() de JS esperan ms; pasaste segundos de 10 dígitos | Multiplicar los segundos por 1000 |
| Milisegundos leídos como segundos | Fecha a miles de años en el futuro | Valor de 13 dígitos pasado a una función en segundos | Dividir primero por 1000 |
| UTC mostrado como hora local | Día correcto, reloj desfasado por tu offset | El conversor eligió por defecto otra zona | Poner el conversor en UTC |
| Hora local copiada sin su offset | Desfasada horas en otra máquina | Una hora de reloj de pared guardada sin zona | Guardar el UTC más la zona horaria |
| Hora de pared ambigua (horario de verano) | Desfasada exactamente una hora cerca de un cambio | Una hora local que ocurre dos veces o nunca | Convertir desde UTC; fijar la zona IANA |
| Micro/nanosegundos leídos como segundos | Fecha lejos en el futuro (16 o 19 dígitos) | Valor de base de datos o de trazado en µs o ns | Dividir por 1.000.000 (µs) o 1.000.000.000 (ns) |
| Fiarse de la precisión mostrada | Parte de subsegundo descartada en silencio | El conversor truncó los milisegundos | Confirmar la unidad que documenta la API destino |
Qué hace un conversor epoch
Un conversor epoch convierte timestamps numéricos en fechas legibles y vuelve a convertir fechas humanas en timestamps epoch. Uno bueno maneja segundos Unix, milisegundos Unix, salida UTC, salida en zona local y cadenas ISO 8601, y hace evidente la unidad antes de que copies un valor en código, una base de datos o una petición de API. Conversor epoch, conversor de hora Unix, conversor de timestamp Unix y calculadora de epoch Unix describen el mismo trabajo: traducir entre un recuento de segundos (o milisegundos) desde el 1 de enero de 1970 UTC y una fecha que un humano pueda leer. El conversor rara vez es el problema — normalmente lo es la entrada.
Los errores de unidad: segundos, milisegundos, micro, nano
El error de conversión más común con diferencia es una confusión de unidad, y tiene una firma: la fecha cae en 1970, o a miles de años. JavaScript es donde más muerde, porque tanto el constructor Date como Date.now() trabajan en milisegundos mientras que la mayoría de las API, bases de datos y el comando Unix date trabajan en segundos. Pasa un valor en segundos de 10 dígitos a new Date() sin multiplicar por 1000 y aterrizas 53 años demasiado pronto. Al revés — alimentar una función en segundos con milisegundos de 13 dígitos — lanza la fecha lejos al futuro. Las fuentes de mayor precisión lo empeoran: las bases de datos suelen emitir microsegundos de 16 dígitos y los sistemas de trazado nanosegundos de 19 dígitos, y ambos parecen un valor Unix válido hasta que se decodifican en el milenio equivocado.
- 10 dígitos → segundos (p. ej. 1700000000); 13 → milisegundos; 16 → microsegundos; 19 → nanosegundos
- JavaScript: new Date(seconds * 1000), o new Date(ms) directamente
- Microsegundos → dividir por 1.000.000 antes de convertir; nanosegundos → por 1.000.000.000
- Comprobación de sentido común: el resultado debe ser una fecha creíble en la década actual
Los errores de zona horaria: UTC vs local y horario de verano
Una vez correcta la unidad, los errores restantes son de zona horaria, y también comparten una firma: la fecha es correcta pero el reloj está desfasado un número entero de horas. Un timestamp Unix es un único instante sin zona propia; el offset solo se aplica al formatear el instante. Así que dos conversores con zonas distintas muestran horas distintas para el mismo número — ninguno se equivoca, solo muestran vistas locales diferentes. La trampa es copiar una hora local de reloj de pared sin anotar de qué zona viene, o convertir una hora que cae en un cambio de horario de verano, donde una hora local puede ocurrir dos veces o ninguna. Cuando un resultado está desfasado exactamente una hora, sospecha del horario de verano antes que del conversor.
- Comparar valores en UTC; aplicar una zona local solo en el momento de mostrarlos
- Nunca guardar una hora local sin guardar también su zona IANA o su offset UTC
- En torno a un cambio de horario de verano, derivar el instante del UTC, no de una hora local ambigua
Elige primero la dirección
La mayoría de las tareas de timestamp van en una de dos direcciones: epoch a fecha, o fecha a epoch. Decidir la dirección primero previene la causa más común de datos de prueba erróneos y payloads de API rotos — convertir el valor correcto en el sentido equivocado.
- Epoch a fecha: pega 1700000000 y lee la fecha UTC o local
- Fecha a epoch: elige 2026-01-01 00:00:00 UTC y obtén 1767225600
- Confirma si el destino espera segundos o milisegundos antes de copiar el resultado
Qué verificar antes de copiar un valor convertido
Un conversor solo puede ser tan correcto como inequívoca sea la entrada. Antes de copiar un timestamp en una prueba, un cron, una migración o una petición de API, confirma la unidad, la zona y la precisión esperada. La comprobación más rápida es el año resultante: una fecha cerca de 1970 o lejos en el futuro casi siempre señala una confusión de unidad más que un error del conversor.
- ¿El sistema receptor espera segundos o milisegundos?
- ¿La fecha mostrada está en UTC o en hora local?
- ¿El timestamp representa un instante o una fecha de calendario local?
- ¿La columna de la base de datos guarda datetime nativo, segundos Unix o milisegundos Unix?
- ¿El resultado está cerca de 1970 o lejos en el futuro, lo que suele señalar una confusión de unidad?
Verificar una conversión en el código
Cuando un valor convertido importa — una migración, un límite de facturación, una programación cron — no confíes en una sola herramienta. Vuelve a derivar el mismo instante en tu propio runtime y comprueba que ambos coinciden en UTC. Cada una de estas líneas imprime una cadena ISO 8601 inequívoca con sufijo Z, así que no hay conjeturas de zona local que comparar.
- JavaScript: new Date(1700000000 * 1000).toISOString() // '2023-11-14T22:13:20.000Z'
- Python: datetime.fromtimestamp(1700000000, tz=timezone.utc).isoformat()
- Shell (GNU): date -u -d @1700000000 +'%Y-%m-%dT%H:%M:%SZ'
- Si la herramienta y tu runtime discrepan, la sospechosa es la unidad o la zona de la entrada — no el conversor
Ejemplo práctico: un instante, tres representaciones
Toma el instante 2026-01-01 00:00:00 UTC. Como segundos Unix es 1767225600; como milisegundos Unix es 1767225600000; como ISO 8601 es 2026-01-01T00:00:00Z. Los tres describen el mismo momento — solo difieren el formato y la unidad. El instante nunca lleva una zona propia; Nueva York mostraría ese mismo valor como 2025-12-31 19:00:00, porque el offset se aplica al mostrar, no se guarda en el número.
Artículos relacionados
FAQ
- ¿Por qué mi fecha convertida cae en 1970?
- Casi siempre porque se leyeron segundos como milisegundos. Date y Date.now() de JavaScript usan milisegundos, así que pasar un valor en segundos de 10 dígitos cae en enero de 1970. Multiplica primero los segundos por 1000.
- ¿Por qué mi hora convertida está desfasada exactamente una hora?
- Es un error de zona horaria o de horario de verano, no un error de cálculo. El conversor aplicó otra zona, o la hora local cayó en un cambio de horario de verano. Pon el conversor en UTC para ver el instante canónico y luego aplica la zona que realmente quieres.
- ¿Cuál es el mejor formato de conversor epoch para copiar?
- Para código, copia segundos o milisegundos Unix según lo que documente la API destino. Para personas, copia ISO 8601 con una Z o un desfase de zona explícito para que el instante sea inequívoco.
- ¿Un conversor epoch es lo mismo que un conversor de hora Unix?
- Para la mayoría de las búsquedas de desarrolladores, sí. Conversor epoch, conversor de hora Unix, conversor de timestamp Unix y calculadora de epoch Unix convierten todos entre timestamps de epoch Unix y fechas legibles.
- ¿Por qué los conversores epoch muestran horas locales distintas?
- Aplican zonas distintas. El instante UTC subyacente es idéntico; solo cambia la visualización local. Pon el conversor en UTC para comparar el valor canónico.
- ¿Cómo sé si mi número está en segundos o en milisegundos?
- Cuenta los dígitos. Un valor moderno de 10 dígitos es en segundos Unix; uno de 13 dígitos es en milisegundos Unix. Si un valor de 10 dígitos cae cerca de 1970 en JavaScript, se trató como milisegundos y debe multiplicarse por 1000.