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.
Maintainers
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-Afterheader all become the same object. - Never guesses. Missing or invalid values are
undefined, never0. - 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-headersIt 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
Headersobject (fromfetch) - a plain object (from Node.js
http, axios, and so on) undefinedornull, 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?
- If the response has a valid
Retry-Afterheader, that value is used. - Otherwise, if
remainingis0andresetAtis known, it is the time untilresetAt. - 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
fetchor 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-resetis 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 exampleMath.min(rate.retryAfterMs, 60_000).- Clock differences. Reset times that are moments in time (GitHub-style, Anthropic,
Retry-Afterdates) are compared with your machine's clock. If it differs from the server's clock, the wait will be off. Retry-Afterwins. If bothRetry-Afterand a reset time are present,Retry-Afteris used.Retry-Afterformats: whole seconds and standard HTTP dates only. Decimals and obsolete date formats are treated as invalid.- Not supported yet: the IETF draft
RateLimitheaders, and Azure'sretry-after-ms. options.nowmust be aDate.
License
MIT
