RFC 3339, ISO 8601, and Unix time: the timestamp formats every API team confuses
A practical guide to the timestamp formats that show up in APIs, logs, and tokens, with clear rules for units, offsets, and normalization.
Tip
Inspect the current certificate, key, token, or endpoint output before changing deployment config; stale artifacts make fixes misleading.
People say “ISO timestamp” as if that phrase tells you enough. It rarely does. In production, the crucial details are the unit, the offset, the precision, and whether the string is actually constrained enough for interoperable parsing.
The shortest practical distinction is that Unix time is numeric seconds or sub-seconds since an epoch, while RFC 3339 is a stricter internet timestamp profile carried as text.
Summary
Definition: Unix time is an epoch-based numeric count, ISO 8601 is a broad family of date and time representations, and RFC 3339 is a constrained profile commonly used on the internet.
Why it matters: Choosing and converting the right representation reduces parsing bugs, timezone mistakes, and token-expiry confusion.
Pitfall: Vague phrases like “ISO date” hide too much. The receiver often needs a more exact contract than that.
Numeric time and textual time solve different problems
Unix time is efficient and easy to compare numerically, which is why it shows up in JWTs, logs, and TTL calculations. RFC 3339 is readable and explicit about offsets, which makes it good for APIs and human inspection. ISO 8601 covers a wider family of representations than most APIs truly want to accept.
That is why teams should document exact accepted forms instead of saying “send an ISO timestamp.”
Precision and offset must be part of the contract
Seconds vs milliseconds vs microseconds can break a system instantly. So can treating a fixed offset as if it were a real time zone. These are not edge cases. They are the normal reasons timestamps fail under pressure.
A converter that shows the same instant in multiple representations is worth more than another explanation paragraph once debugging begins.
- Document units for Unix time explicitly.
- Use RFC 3339 when text timestamps need clear offset rules.
- Do not use “ISO 8601” as a substitute for an actual accepted format contract.
Why this matters across the site
Tokens, cron jobs, signed URLs, replay windows, and logs all intersect with time handling. A useful timestamp workflow should make unit, zone, and expiry assumptions visible instead of hiding them behind one generic converter.
Quick example
Use this when you need to explain the same instant in the three formats teams mix up most often.
What to notice: The same instant can be represented different ways. The important part is making the accepted form explicit.
Unix seconds: 1775300400
RFC 3339: 2026-04-03T22:00:00Z
ISO 8601: family of forms; document the exact one you accept
Practical check
- Write down units before comparing numeric timestamps.
- Specify the accepted text timestamp format more precisely than “ISO.”
- Treat offset and time zone as different pieces of information.
FAQ
Is RFC 3339 the same thing as ISO 8601?
RFC 3339 is a more constrained profile in the ISO 8601 family space, often used to improve interoperability.
Should APIs prefer text or numeric timestamps?
It depends on the job. Numeric values are compact and easy to compare; RFC 3339 text is clearer for many API contracts.
Developer workflow
Use this guide as an operations checklist before changing certificates, tokens, DNS, or deployment settings.
- Inspect the current artifact or endpoint output before making changes.
- Change one variable at a time so a failed verification has a narrow cause.
- Keep the rollback value, expiry, and verification command in the same runbook entry.
1. current deployed artifact
2. single config or key change
3. verify endpoint/client behavior
4. record rollback and expiry details