RateLimiter
Defined in: packages/rest/src/limiter.ts:52
Owns Discord’s rate-limit state: when a request may go out, and what a response says about the bucket it landed in.
The limiter holds no queueing logic of its own — RequestScheduler decides ordering — and no HTTP knowledge beyond reading rate-limit headers.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new RateLimiter(
store,options?):RateLimiter
Defined in: packages/rest/src/limiter.ts:75
Parameters
Section titled “Parameters”Rate-limit state store.
options?
Section titled “options?”maxBackoff: the most, in ms, that a rate-limit header can
make later requests wait (default 10 minutes). probeMs: how long a
request discovering an unknown bucket holds it (default 16 s; keep it
above the transport timeout). globalLimit: most requests per second
per global scope, enforced before Discord answers 429 (default none;
REST passes 50). telemetry: event sink. concurrent is
accepted for compatibility: responses are always merged so a late one
cannot raise remaining.
concurrent?
Section titled “concurrent?”boolean
globalLimit?
Section titled “globalLimit?”number
maxBackoff?
Section titled “maxBackoff?”number
probeMs?
Section titled “probeMs?”number
telemetry?
Section titled “telemetry?”Returns
Section titled “Returns”RateLimiter
Accessors
Section titled “Accessors”maxBackoff
Section titled “maxBackoff”Get Signature
Section titled “Get Signature”get maxBackoff():
number
Defined in: packages/rest/src/limiter.ts:99
The ceiling on a wait a server header can cause, in ms.
Returns
Section titled “Returns”number
reserves
Section titled “reserves”Get Signature
Section titled “Get Signature”get reserves():
boolean
Defined in: packages/rest/src/limiter.ts:114
Whether the backing store can reserve allowance atomically.
Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get store():
RateLimitStore
Defined in: packages/rest/src/limiter.ts:109
The backing store, shared across processes when a distributed store is used.
Returns
Section titled “Returns”Methods
Section titled “Methods”acquire()
Section titled “acquire()”acquire(
initialKey,signal,path,options?):Promise<Grant>
Defined in: packages/rest/src/limiter.ts:180
Waits until both the route bucket and the global limit permit sending.
When the store supports it, allowance is reserved rather than merely
observed. Reading remaining and deciding to send is a race across
workers: three processes all read remaining: 1 and all send. A
reservation hands the unit to exactly one of them. A request is never
sent without its reservation: a store that keeps refusing without a
wait, or that fails, ends the request with a "coordination" error.
Parameters
Section titled “Parameters”initialKey
Section titled “initialKey”string
signal
Section titled “signal”AbortSignal | undefined
string
options?
Section titled “options?”global?
Section titled “global?”string
resolve?
Section titled “resolve?”() => Promise<string>
Resolves the request’s bucket key again. Called after waiting on another worker’s probe: its response may have revealed the shared bucket, whose key differs from the route-derived one.
Returns
Section titled “Returns”Promise<Grant>
Throws
Section titled “Throws”"aborted" on cancellation, "coordination" on a
broken store, "rateLimited" when waiting would exceed maxBackoff.
applyResponse()
Section titled “applyResponse()”applyResponse(
response,bucketKey,route,major,options?):Promise<string>
Defined in: packages/rest/src/limiter.ts:404
Records a response’s rate-limit headers and returns the bucket key the request actually belongs to: Discord may reveal a server bucket hash that differs from the route-derived key used before the first response.
Parameters
Section titled “Parameters”response
Section titled “response”Response
bucketKey
Section titled “bucketKey”string
string
string
options?
Section titled “options?”ApplyResponseOptions = {}
Returns
Section titled “Returns”Promise<string>
noteGlobalReset()
Section titled “noteGlobalReset()”noteGlobalReset(
resetAt,scope?):Promise<void>
Defined in: packages/rest/src/limiter.ts:368
Extends the global limit (of scope), never shortening a longer one
already recorded. Atomic when the store has extendGlobalReset.
Parameters
Section titled “Parameters”resetAt
Section titled “resetAt”number
scope?
Section titled “scope?”string = ""
Returns
Section titled “Returns”Promise<void>
releaseGrant()
Section titled “releaseGrant()”releaseGrant(
bucketKey,grant,notSent):Promise<void>
Defined in: packages/rest/src/limiter.ts:502
Gives back what a grant held when the request did not get a response:
a probe placeholder is always cleared; the unit itself is returned only
with notSent (the request certainly never left), because a request
that may have reached Discord may also have spent it.
Parameters
Section titled “Parameters”bucketKey
Section titled “bucketKey”string
notSent
Section titled “notSent”boolean
Returns
Section titled “Returns”Promise<void>
resolveBucketKey()
Section titled “resolveBucketKey()”resolveBucketKey(
route,major,identity?):Promise<string>
Defined in: packages/rest/src/limiter.ts:129
Resolves the bucket key a request should be gated on. With an
identity, the key is prefixed by it, so two bots never share a bucket.
Parameters
Section titled “Parameters”string
string
identity?
Section titled “identity?”string
Returns
Section titled “Returns”Promise<string>
retryAfterMs()
Section titled “retryAfterMs()”retryAfterMs(
response,body?):number
Defined in: packages/rest/src/limiter.ts:384
How long a 429 asks to wait, in ms: the body’s retry_after, else the
Retry-After header, else X-RateLimit-Reset-After, else one second.
Negative or non-numeric values are ignored, not read as zero.
Parameters
Section titled “Parameters”response
Section titled “response”Response
retry_after?
Section titled “retry_after?”number
Returns
Section titled “Returns”number