npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ratelimit-headers

v0.1.0

Published

Normalize HTTP rate-limit headers from GitHub, OpenAI, Anthropic and the standard Retry-After header into one consistent result.

Readme

ratelimit-headers

Read rate-limit headers from any HTTP response and get one consistent result: how many requests are left, when the limit resets, and how long to wait.

import { normalizeRateLimit } from "ratelimit-headers";

const rate = normalizeRateLimit(response.headers);
// {
//   provider: "github",
//   limit: 60,
//   remaining: 0,
//   resetAt: 2026-09-20T07:12:57.000Z,
//   retryAfterMs: 312000
// }
  • One shape for every API. GitHub-style headers, OpenAI, Anthropic and the standard Retry-After header all become the same object.
  • Never guesses. Missing or invalid values are undefined, never 0.
  • Never throws because of bad header data.
  • Zero dependencies. It only reads headers. It does not make requests, retry, sleep or keep any state.
  • Written in TypeScript, types included.

Early release (0.x): the API may change before 1.0.

Why

Every API reports rate limits in its own way:

| API | Header | Reset time is... | | ------------ | ------------------------------------ | ------------------------------------------------------------ | | GitHub-style | x-ratelimit-reset | a Unix timestamp in seconds (1789888377), a moment in time | | OpenAI | x-ratelimit-reset-requests | a duration (1m5.013s), time from now | | Anthropic | anthropic-ratelimit-requests-reset | an RFC 3339 timestamp (2026-09-20T07:08:15Z) | | Standard | Retry-After | seconds (120) or an HTTP date |

Handling all of them means one parser per API. This package does it once, so your code only deals with one result.

Install

npm install ratelimit-headers

It works with both import and require, and uses no Node.js-specific APIs, so it should also work in browsers and other modern runtimes. The built package is tested on Node.js 18, 20, 22 and 24.

Usage

The package never waits or retries for you. It tells you how long to wait, and you decide what to do.

With fetch

import { normalizeRateLimit } from "ratelimit-headers";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function get(url: string) {
  const response = await fetch(url);
  const rate = normalizeRateLimit(response.headers);

  if (response.status === 429 && rate.retryAfterMs !== undefined) {
    await sleep(Math.min(rate.retryAfterMs, 60_000));
    return fetch(url);
  }
  return response;
}

With axios

import axios from "axios";
import { normalizeRateLimit } from "ratelimit-headers";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function get(url: string) {
  try {
    return await axios.get(url);
  } catch (error) {
    if (axios.isAxiosError(error)) {
      // `error.response` can be missing (for example on a network error). That is fine.
      const rate = normalizeRateLimit(error.response?.headers);
      if (rate.retryAfterMs !== undefined) {
        await sleep(Math.min(rate.retryAfterMs, 60_000));
        return axios.get(url);
      }
    }
    throw error;
  }
}

Math.min(..., 60_000) caps the wait at one minute. It is a good habit, see Limitations.

API

normalizeRateLimit(headers, options?)

headers can be:

  • a Headers object (from fetch)
  • a plain object (from Node.js http, axios, and so on)
  • undefined or null, which is treated as "no headers"

Header names are case-insensitive. Values can be strings, numbers or arrays.

options.now is a Date used as "the current time". It defaults to new Date(). It is mostly useful in tests.

Result

normalizeRateLimit always returns an object with all five fields:

| Field | Type | Meaning | | -------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- | | provider | "github" \| "openai" \| "anthropic" \| "standard" \| "unknown" | Which header format was recognized | | limit | number \| undefined | Total requests allowed in the current window | | remaining | number \| undefined | Requests left. undefined means unknown, not zero | | resetAt | Date \| undefined | When the limit resets | | retryAfterMs | number \| undefined | How long to wait, in milliseconds, before the next request |

When is retryAfterMs set?

  1. If the response has a valid Retry-After header, that value is used.
  2. Otherwise, if remaining is 0 and resetAt is known, it is the time until resetAt.
  3. Otherwise it is undefined.

It is never negative. A time that is already in the past gives 0.

provider

| Value | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | "anthropic" | anthropic-ratelimit-* headers were found | | "openai" | x-ratelimit-*-requests or x-ratelimit-*-tokens headers were found | | "github" | GitHub-style x-ratelimit-limit, -remaining and -reset headers were found. Many other APIs use the same names | | "standard" | Only a Retry-After header was found | | "unknown" | Nothing recognized |

The most specific format wins, in the order above. A Retry-After header is read whatever the provider is.

Types

RateLimitResult, RateLimitProvider, NormalizeOptions, HeadersInput, HeadersLike and HeadersRecord are exported.

Examples

// GitHub-style, limit reached
normalizeRateLimit(
  {
    "x-ratelimit-limit": "60",
    "x-ratelimit-remaining": "0",
    "x-ratelimit-reset": "1789888377",
  },
  { now: new Date("2026-09-20T07:07:45Z") },
);
// { provider: "github", limit: 60, remaining: 0,
//   resetAt: 2026-09-20T07:12:57.000Z, retryAfterMs: 312000 }

// OpenAI, requests still available (the reset is a duration from now)
normalizeRateLimit(
  {
    "x-ratelimit-limit-requests": "10000",
    "x-ratelimit-remaining-requests": "9992",
    "x-ratelimit-reset-requests": "1m5.013s",
  },
  { now: new Date("2026-09-20T07:07:45Z") },
);
// { provider: "openai", limit: 10000, remaining: 9992,
//   resetAt: 2026-09-20T07:08:50.013Z, retryAfterMs: undefined }

// Only a standard Retry-After header
normalizeRateLimit({ "retry-after": "120" });
// { provider: "standard", limit: undefined, remaining: undefined,
//   resetAt: undefined, retryAfterMs: 120000 }

// No headers at all
normalizeRateLimit(undefined);
// { provider: "unknown", limit: undefined, remaining: undefined,
//   resetAt: undefined, retryAfterMs: undefined }

What this package does not do

  • It does not make HTTP requests, and it does not replace fetch or axios.
  • It does not retry, sleep or wait.
  • It does not count your requests or keep any state. The server's headers are the source of truth.
  • It does not rate-limit your own server. For that, look at packages such as express-rate-limit.

Alternatives

ratelimit-header-parser reads the IETF draft RateLimit-* headers and plain X-RateLimit-* headers, and lets you choose how the reset value is parsed. This package does not support the IETF draft headers yet. In our tests, version 0.1.0 of ratelimit-header-parser returned nothing for Retry-After, OpenAI-style or Anthropic-style headers, and it does not calculate a wait time. That is what this package is for.

Limitations

  • OpenAI and Anthropic: only request limits are read. Token limits (...-tokens-...) are ignored, even though they are often the limit you hit first with AI APIs.
  • x-ratelimit-reset is assumed to be in seconds. A value in milliseconds is not detected, and can give a date far in the future. This is one reason to cap your waits, for example Math.min(rate.retryAfterMs, 60_000).
  • Clock differences. Reset times that are moments in time (GitHub-style, Anthropic, Retry-After dates) are compared with your machine's clock. If it differs from the server's clock, the wait will be off.
  • Retry-After wins. If both Retry-After and a reset time are present, Retry-After is used.
  • Retry-After formats: whole seconds and standard HTTP dates only. Decimals and obsolete date formats are treated as invalid.
  • Not supported yet: the IETF draft RateLimit headers, and Azure's retry-after-ms.
  • options.now must be a Date.

License

MIT