Skip to main content

Nirn Proxy

Nirn Proxy is a transparent HTTP proxy that sits between your bots and the Discord REST API. It tracks rate limit buckets, makes requests wait when nothing is left to spend, and exports Prometheus metrics. Adopting it only takes changing the API URL in your library.

The original project, germanoeich/nirn-proxy, born at Dyno, was archived in March 2026. Our fork starts from its last commit and fixes, one by one, the bugs found in the other forks, each with a test that fails without the fix. The details are in Fork fixes.

Features​

  • High availability: several nodes in a cluster, with no quorum and no external storage.
  • Per-route and global limits handled transparently, requests sent in order for each bucket.
  • Every API version, including several at once for the same bot.
  • Webhooks and Bearer tokens supported, for any number of bots and clients.
  • No hardcoded routes: new Discord routes work without an update.
  • Prometheus metrics out of the box, including the invalid requests that lead to a Cloudflare ban.

How it behaves​

The proxy listens on every route and relays it to Discord without changing the request: any library compatible with the Discord API works behind it, even with its own rate limiting on. You can also remove it and fire requests right away.

The proxy does not retry requests. If it still gets a 429 (shared limit, Discord internal limit…), it returns it to the client, which can retry immediately. It also guards against situations known to cause a Cloudflare ban, such as too many webhook 404s or too many 401s.

Proxy specific responses​

  • 408 Request Timeout: Discord took more than REQUEST_TIMEOUT milliseconds to answer, or the request was aborted because of rate limits.
  • 429 with the generated-by-proxy header: a cluster node went down; the client is told to wait one second before retrying (see High availability).

Limitations​

  • The proxy does not handle SSL: serve it on a private network.
  • Rate limiting only works with X-RateLimit-Precision set to seconds, the only possible behavior since API v8.
  • Discord does not expose a bot's global limit: declare raised limits with BOT_RATELIMIT_OVERRIDES.

Checking the proxy​

We check the fork with Bucketmap, which walks every Discord REST route and compares what Discord answers with what the proxy answers: see Testing a proxy.

License​

Nirn Proxy is released under the GPL v3 license. The source code is on GitHub, on the fixes branch.