How to Read and Debug Timestamps in API Responses
REST APIs return timestamps in many shapes and forms: Unix epoch integers, ISO 8601 strings, RFC 2822 dates, and occasionally proprietary formats. Misreading a timestamp in an API response can lead to subtle bugs that are hard to track down — wrong timezone displays, off-by-one-day errors, and time-range queries that return no results. This guide shows you exactly how to read, interpret, and debug timestamps in API responses efficiently.
Common Timestamp Formats in API Responses
Before debugging a timestamp, you need to identify its format. APIs use several common formats, each with different characteristics. Unix epoch seconds (integer): The most compact format. Example: 1715500800. It is always UTC, easy to store, and easy to do arithmetic on. Most common in older APIs and Unix-heritage systems. Unix epoch milliseconds (integer): The same as above but multiplied by 1000. Example: 1715500800000. Common in JavaScript-native APIs because Date.now() returns milliseconds. A frequent source of confusion when mixing JavaScript and Python code. ISO 8601 string with UTC offset: Example: '2026-05-12T00:00:00Z' or '2026-05-12T02:00:00+02:00'. The 'Z' suffix means UTC. The offset (+02:00) encodes the timezone directly in the string. This format is the most human-readable and is self-describing about timezone. RFC 2822 string: Example: 'Mon, 12 May 2026 00:00:00 +0000'. Used in email headers and some older web APIs. Parseable by most date libraries. Custom formats: Some older or proprietary APIs use formats like 'YYYYMMDDHHMMSS' or '/Date(1715500800000)/' (ASP.NET's legacy JSON date format). These require extra parsing. Knowing which format you are looking at is the first step. An integer with 10 digits is almost certainly epoch seconds. An integer with 13 digits is almost certainly epoch milliseconds. A string starting with a 4-digit year followed by dashes is almost certainly ISO 8601.
Step-by-Step Process for Debugging a Timestamp Bug
When a timestamp-related bug appears — a date showing incorrectly, an event appearing in the wrong time range, or a scheduled job firing at the wrong time — follow this systematic process. Step 1: Find the raw value. Examine the API response as raw JSON before any parsing. Use a tool like Postman, curl with pretty-print, or a browser's Network tab. Write down the exact raw value including its type (number or string). Step 2: Identify the format. Determine whether it is epoch seconds, epoch milliseconds, or a date string. Apply the digit-count heuristic for integers: 10 digits = seconds, 13 digits = milliseconds. Step 3: Convert to human-readable form. Paste the value into a Unix Timestamp Converter and note the resulting UTC date and local date. Does it match what you expected? If not, the bug is either in the value itself or in your expectation. Step 4: Trace where the conversion happens in your code. Find the line where the raw timestamp is converted to a display date. Check whether the timezone conversion is correct. Confirm that the unit (seconds vs milliseconds) matches what the conversion function expects. Step 5: Check the API documentation. Confirm the API's documented behavior: is the timestamp in UTC? Is it seconds or milliseconds? Does the API apply any timezone adjustments? Sometimes APIs return timestamps in the server's local timezone, which is a bug in the API — but knowing this helps you work around it. Step 6: Add a test. Once you have found and fixed the bug, add a unit test that verifies a specific known timestamp converts to the expected date. This prevents regression.
The Most Frequent Timestamp Bugs in APIs and How to Fix Them
After debugging hundreds of API integrations, certain timestamp bugs appear over and over. Here are the most common ones and their fixes. Bug: Milliseconds passed to a seconds-expecting function. Symptom: dates appear 1000 times further in the future than expected, often showing years like 53,000 AD. Fix: Divide the value by 1000 before passing it, or use a function that explicitly accepts milliseconds. Bug: Local time stored as UTC. Symptom: times are consistently off by a fixed number of hours (often matching the server's timezone offset). Fix: Normalize all timestamps to UTC before storage. If you cannot fix the API, apply the inverse offset when reading values. Bug: Timezone-naive date parsing. Symptom: times shift by hours around DST transitions. Fix: Always specify the timezone when parsing date strings. In Python use pytz or zoneinfo. In JavaScript use a library like date-fns-tz. Bug: Integer overflow on 32-bit systems. Symptom: timestamps for dates after January 2038 wrap around to negative values or epoch. Fix: Migrate to 64-bit integer columns in the database. This is urgent for any system that stores future dates beyond 2038. Bug: Rounding errors with floating-point timestamps. Symptom: times are off by a second occasionally. Fix: Store timestamps as integers (not floats). Python's time.time() returns a float, so cast with int() before storage.
Tools and Techniques for Fast Timestamp Inspection
Speed matters when debugging. Here are the fastest ways to inspect timestamps across different contexts. In the browser console: new Date(1715500800 * 1000) instantly shows a readable date. Omit the multiplication if the timestamp is already in milliseconds. You can also use new Date(1715500800000).toISOString() for the UTC string. In the terminal (Linux/macOS): date -d @1715500800 converts a timestamp using the system's date command. On macOS: date -r 1715500800. In Python (one-liner): python3 -c "from datetime import datetime; print(datetime.utcfromtimestamp(1715500800))" gives a quick UTC date without writing a script. Online converter: Fastest for quick checks during code review or when looking at a log file. Our Unix Timestamp Converter handles seconds and milliseconds automatically and shows UTC plus local time without requiring you to remember any syntax. In database queries: SELECT FROM_UNIXTIME(1715500800) in MySQL or SELECT TO_TIMESTAMP(1715500800) in PostgreSQL gives you the date directly in the database client. Building a habit of reaching for one of these tools the moment you see a suspicious number in a response or log will save you significant debugging time over a career.
Frequently Asked Questions
- How do I know if an API timestamp is in seconds or milliseconds?
- Count the digits. In 2026, a second-precision Unix timestamp has 10 digits (around 1,747,000,000). A millisecond-precision timestamp has 13 digits (around 1,747,000,000,000). You can also cross-check by converting the value to a date with our converter: if the date looks reasonable, the unit is correct. If it shows a date far in the future or in 1970, you have the wrong unit.
- Why is my API returning a timestamp that's off by exactly one hour?
- An offset of exactly one hour typically means a Daylight Saving Time mismatch. The timestamp is being converted to the wrong DST state, or the server is in a timezone that differs from the expected one by exactly one hour. Always convert timestamps to UTC for storage and apply the correct IANA timezone (like 'America/New_York') rather than a fixed offset like '-5:00' which does not account for DST.
- Can I trust that all REST APIs return timestamps in UTC?
- Best practice says yes, but not all APIs follow best practices. Most major APIs (Stripe, GitHub, Twilio, AWS) reliably return UTC timestamps. Smaller or older APIs sometimes return local server time without documenting it. Always verify by checking a timestamp you know the expected value for — convert it with our tool and compare the UTC result against what you expect.