Rate Limiter API

A simple library to easily manage rate limits of APIs without any hassles.

The maintained npm releases are 1.0.12 (compatible Stampit/callback API, Node 6+, install with @legacy) and 2.0.0 (modern ESM/CommonJS/TypeScript, Node 22+, install with @latest). Both were published on 12 October 2026 with signed GitHub Actions provenance and use a shared scheduler and regression tests.

• Compatible 1.x usage
• Modern 2.x usage and migration
• Build, tests, CI and release instructions

The repository root is a private build project. Run npm ci --ignore-scripts and npm run check to verify both packed releases. The older usage guide below describes the callback API; use the release guides for current exports, reset units and supported options.

Table of Contents

• How to Use
  • Browser
  • NodeJS
• Public API
• Stats
• Technologies Used
• Help & Support
• Contributors
• License
• Contact

Usage ⮭

Browser ⮭

<script src="https://cdn.jsdelivr.net/npm/rate-limiter-api@1.0.12/dist/rate-limiter-api.js"></script>

<script type="text/javascript">
  var rateLimiter = RateLimiterAPI()
</script>

NodeJS ⮭

npm install rate-limiter-api@legacy

import RateLimiterAPI from 'rate-limiter-api'

Public Interface ⮭

• rateLimiter = RateLimiterAPI({threshold: 5})
• rateLimiter.limit(requestHandler) => Promise
  • rateLimiter.updateRateLimits on success to update rates
  • requestHandler(responseHandler) on success to continue

---

import RateLimiterAPI from 'rate-limiter-api'

const rateLimiter = RateLimiterAPI({
  threshold: 5, // leave `threshold` amount of api requests intact (minimum: 1)
})

Pass an optional threshold value which would limit the total rate limits till the threshold is reached in the current session pulse till rate reset.

---

const request = rateLimiter.limit(requestHandler) //=> Promise

function requestHandler(responseHandler) {
  fetch('https://api.example.com/get')
    .then((response) => {
      rateLimiter.updateRateLimits({
        rateLimit: response.headers.get('X-RateLimit-Limit') || undefined,
        rateRemaining: response.headers.get('X-RateLimit-Remaining') || undefined,
        rateReset: response.headers.has('X-RateLimit-Reset')
          ? Number(response.headers.get('X-RateLimit-Reset')) * 1000 : undefined,
      })

      responseHandler(null, response.body)
    })
    .catch((err) => {
      responseHandler(err)
    })
}

The limit method is passed a requestHandler which would manage the request and then call the node-style responseHandler callback (which gets passed by the RateLimiter library to the requestHandler function) after the request is successful or unsuccessful accordingly.

The request method returns a Promise.

responseHandler(Error, response)
where the first parameter is the Error object and the seconds parameter is the response.

responseHandler callback must be called to continue getting responses.

Update the rate limits i.e. {rateLimit, rateRemaining, rateReset} got from the header using updateRateLimits method.

---

request
  .then((response) => {
    console.dir(response, {colors:1})
  })
  .catch((error) => {
    console.error(error.message)
  })

When the request completes, the Promise resolves and can be thenable to get the response or error.

Stats ⮭

1 text file.
1 unique file.
0 files ignored.

https://github.com/AlDanial/cloc v 1.66 T=0.04 s (22.7 files/s, 2516.9 lines/s)

Language	files	blank	comment	code
JavaScript	1	12	37	62

Technologies Used ⮭

• Babel — Transpiles modern JS to compatible and runnable JS
• Stamp It - Composable inheritance object creation libray
• Async JS - Utility for asynchronous functions
• Lodash - Utility library

Help & Support ⮭

• BabelJS — BabelJS Slack Chat Room
• nodejs/node — NodeJS Gitter Chat Room
• Fun with Stamps - Learn StampIt

Contributors ⮭

Abhisek Pattnaik 💻 🎨 📖 💡

This project follows the all-contributors specification.

All types of Contributions are Welcome 🙏

License ⮭

MIT © Abhisek Patnaik

---

Tweet @abhisek
Know about/abhisekp
Chat with @abhisekp

---

Table of Contents ⮭
back to top ⮭