Free tools Windows power users keep installed
One-click scans. No signup required.
Most timestamp bugs at an API boundary come from one of three gaps in the contract. The time has no explicit timezone, a named timezone is reduced to a fixed offset, or the numeric representation’s epoch, units, precision, and range are never stated. Each gap can pass a happy-path test and then fail when a client in another region, a stored value, or a boundary date enters the picture.
This article covers each gap, what the IETF specifications say about it, and the decisions an API contract should make. The guidance is implementation-neutral. Parsers, language runtimes, and databases differ in how they handle edge cases, so confirm the behavior of the specific stack you run before relying on any code-level assumption.
As an Amazon Associate I earn from qualifying purchases.
Bug 1: A timestamp without a timezone does not name one instant
A bare local date-time such as 2026-10-25T01:30:00 looks complete, but it may not identify a single point in time. Whether it does depends on which zone the producer and consumer assume, and two services with different defaults can read the same string differently.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsWhat the standard requires
The Internet date-time profile in RFC 3339 requires a complete date and time with either a Z suffix for UTC or a numeric offset. Its own example shows two spellings of one instant: 1996-12-19T16:39:57-08:00 is the same moment as 1996-12-20T00:39:57Z.
#1 Best Overall
The same section explains why unqualified local time is a problem for protocols. The RFC states, in section 4.1:
“Because the daylight saving rules for local time zones are so convoluted and can change based on local law at unpredictable times, true interoperability is best achieved by using Coordinated Universal Time (UTC).”
Decisions the API contract should make
- Whether every incoming timestamp must carry
Zor an explicit offset, and whether a bare date-time is rejected or handled by a documented fallback. - Whether the service accepts only UTC, or accepts offsets and normalizes them before storage.
- Whether every returned instant is normalized to UTC, and whether the response format is fixed or varies by request.
- If the product accepts user-local input, where the zone comes from. It should be explicit data, such as a field the client sends, not something the server guesses.
- How ambiguous local times (a wall-clock hour that occurs twice when clocks fall back) and nonexistent local times (an hour skipped when clocks spring forward) are resolved.
How one vendor resolves the question
GitHub’s REST documentation states that the timestamps it returns are UTC in ISO 8601 format. For applicable requests, it also defines a precedence order for timezone selection. The order below is GitHub’s policy, not a universal rule, and it applies only where the endpoint’s documentation says it does, as described on GitHub’s timezones page:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →- An explicitly supplied ISO 8601 timestamp that includes timezone information.
- A
Time-Zonerequest header. - The last known timezone for the authenticated user.
- UTC.
The ordering is useful as an example because it makes the fallback explicit. A contract that lets a server silently pick a fallback zone reproduces the original bug in a different place.
Bug 2: An offset is not a timezone
A numeric offset such as -05:00 tells a parser how one particular local timestamp relates to UTC. It does not tell you how that location’s clock will move in the future. The two concepts are easy to confuse because they often look alike in output.
RFC 9557 draws the distinction directly. In its definition of “Time Zone,” it states:
“Unlike the UTC offset of a timestamp, which makes no claims about the UTC offset of other related timestamps (and which is therefore unsuitable for performing local-time operations, such as ‘one day later’), a time zone also defines how to derive new timestamps based on differences in local time.”
Recommended Free Tools
The RFC also notes that IANA time-zone rules can change, so a zone identifier alone does not freeze future behavior.
Rank #2
| Property | UTC offset (for example, -05:00) |
Named zone (for example, America/New_York) |
|---|---|---|
| What it describes | The difference from UTC for one timestamp | The rules relating local time to UTC for a location |
| Can it compute the local time one day or one season later? | No. It makes no claim about other timestamps | Yes, when the rules are applied to the date in question |
| Stability over time | Fixed for the timestamp it accompanies | Can change when the rules change, so the rule version matters |
| Suited to | Recording when something happened | Recurring or future local-time commitments |
The same location shows the difference. New York uses -05:00 during standard time and -04:00 during daylight saving time. A stored -05:00 tells you the offset at that moment and nothing about what a 9:00 a.m. meeting next July should be.
Choosing a behavior when the offset and zone disagree
Some data carries both an offset and a zone. RFC 9557 says that a mismatch with a critical zone suffix must be acted on, and the resolution can be either rejecting the timestamp or fixing the inconsistency with additional information. The contract should state which one applies.
For future local events, the system also needs a policy for rule changes. The main options are:
- Apply the zone rules in effect when the event is interpreted, so the event follows any change to the zone.
- Preserve the offset recorded at creation, so the event keeps its original instant even if the zone changes later.
- Ask the user to confirm when a stored event no longer matches the current rules.
Each option has a cost. The first can move an appointment when a government changes its clock rules. The second can leave it at a time the user no longer intended. The third adds friction, but it is the only option that avoids silent changes.
Bug 3: Representation limits are invisible unless you state them
An integer timestamp is not self-describing. Its meaning depends on an epoch, a unit, a precision, and a range. If any of these is left implicit, a value can be correct in one system and wrong in another.
Seconds versus milliseconds
Mismatched units are one of the most direct hazards. A value in seconds read as milliseconds is 1,000 times too small, so a current timestamp lands only about 20 days after the 1970 epoch. The reverse produces a date far in the future. The contract should name the unit in the field name or the schema, and the examples in the documentation should use the same unit as the schema.
Fractional precision
Precision can shrink as a value crosses layers. A nanosecond value may be truncated to microseconds by one library, or to whole seconds by a column type, without any error. RFC 8877 lists resolution as one of the factors in choosing a timestamp format, and it notes that the format chosen should reflect the resolution a protocol actually needs. An API should state the finest precision it promises and whether it truncates or rounds values that exceed it.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Range and wraparound
RFC 8877 uses NTP packet formats to show what wraparound means in practice. Its figures apply to those NTP formats only and should not be generalized to all API timestamps:
| NTP format (as described in RFC 8877) | Resolution or wraparound stated in RFC 8877 | Practical implication |
|---|---|---|
| 32-bit timestamp | Wraps roughly every 18 hours | Too short a range for records that must be compared across days |
| 64-bit timestamp | Wraps roughly every 136 years; next wraparound in 2036 | Long range, but a fixed wrap point that code must handle |
| 64-bit fractional field | Resolution of 2^-32 seconds, roughly 233 picoseconds | Finer than most application needs, so precision is rarely the limit here |
Signed and unsigned fields add a separate risk. A signed 32-bit count of seconds since 1970 runs out in January 2038, which is a general property of that field width rather than something RFC 8877 states. A parser that reads an unsigned value as signed, or the reverse, can produce negative dates for values that were valid when written.
Testing the boundaries
Testing typical values will not reveal most representation defects. The useful checks are at the edges:
- The epoch itself and one unit either side of it.
- The smallest and largest values the contract accepts, and the first value just outside each limit, which should be rejected or handled as documented.
- Values with the maximum fractional precision, and the same values after a round trip through each storage and serialization layer.
- Any wraparound point that applies to the chosen format, including the moment of rollover.
Synchronization and leap seconds
A timestamp can be syntactically valid and still be wrong. Validity checks confirm the shape of the value, not that the producing clock was accurate. RFC 8877 says a protocol specification should describe its synchronization assumptions, including whether nodes are synchronized and whether timestamps come from a reference clock such as an NTP server. It also calls for accuracy, precision, and leap-second considerations.
Leap seconds are where clocks most often disagree. RFC 8877 notes that leap-second handling depends on the synchronization protocol, and that a leap smear spreads the adjustment across seconds to hours. RFC 3339 permits a seconds value of 60 for an announced leap second, subject to its rules, and cautions that leap seconds cannot be predicted far in advance.
The practical step is to state the timescale your API uses and the leap-second policy your producers follow. Also decide whether your parser accepts a seconds value of 60, because a library that does not handle it may reject a valid timestamp or fail on it.
Choosing a representation for each use case
The three bugs share a root cause: the contract did not say what kind of time the field carries. The table below maps common cases to the representation that answers the question each one asks.
| Use case | Representation to specify | Why |
|---|---|---|
| Recording when an event happened (logs, audit records, webhooks) | UTC instant, with Z or an explicit offset |
Identifies one moment and needs no future rules |
| A recurring local commitment (a 9:00 a.m. weekly meeting) | Local date-time plus a named zone and a stated rule-change policy | The offset for the event will change across seasons, so the zone defines the intent |
| Integer timestamps exchanged with another system | Documented epoch, unit, precision, valid range, and wraparound behavior | Prevents unit mismatch, silent truncation, and overflow |
| Elapsed time within a process or between two measurements | A duration or monotonic measurement, not a wall-clock timestamp | Wall clocks can be adjusted, so differences between them can be negative or wrong |
Each row is a different question. The defect appears when an API answers one question with a representation designed for another.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
