Documentation Issue: X-RateLimit-Reset should not be a Date object

[Fdavidtr]

The current documentation shows an example where the X-RateLimit-Reset header is set using a Date object:

'X-RateLimit-Reset': new Date(Date.now() + rateLimiterRes.msBeforeNext)

This results in a string like:

Wed, 03 Apr 2025 16:34:50 GMT

However, this is not aligned with common practices. Most APIs (e.g. GitHub, Stripe, Twitter) return X-RateLimit-Reset as a Unix timestamp in seconds — not a formatted date string.

---

❌ Why this is problematic

• Formatted strings are harder to parse and less predictable.
• Unix timestamps are machine-friendly and easier to consume for clients or automated retry logic.
• The IETF draft spec recommends using either a timestamp or delta in seconds — not a stringified date.
• Using a Date string breaks compatibility with clients expecting numeric values (e.g. retry logic like setTimeout(Number(reset) - Date.now()) fails).

---

✅ Suggested fix in the docs

Update the example to use:

'X-RateLimit-Reset': Math.floor((Date.now() + rateLimiterRes.msBeforeNext) / 1000)

This way, the header is:

• Numeric ✅
• UTC-based ✅
• Easily comparable ✅
• Standards-compliant ✅

---

📚 References

• IETF Draft: https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html
• GitHub API Rate Limiting: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
• Twitter API Rate Limiting: https://developer.twitter.com/en/docs/twitter-api/rate-limits

Thanks!

[animir]

@Fdavidtr Good catch!
Could Math.floor call lead weird cases when a request is made after X-RateLimit-Reset, but 429 is still returned from API?
E.g. (Date.now() + rateLimiterRes.msBeforeNext) / 1000 = 5,950 ms, X-RateLimit-Reset=5 in this case. Some automated software makes a request in 5 seconds and a request is still prohibited after 5,120 ms.

Would Math.ceil call do a better job here?

[Fdavidtr]

You're right, using Math.floor could lead to unexpected 429s just before the actual reset time. Switching to Math.ceil makes sense to avoid those edge cases.

[animir]

I fixed the example.
Thank you.