REST
Defined in: packages/rest/src/index.ts:287
Bun-native REST transport with Discord bucket-aware rate limiting, retries, and cancellation.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new REST(
options?):REST
Defined in: packages/rest/src/index.ts:317
Creates a REST transport.
Parameters
Section titled “Parameters”options?
Section titled “options?”Transport configuration.
allowInsecureBaseURL?
Section titled “allowInsecureBaseURL?”boolean
Allow a cleartext http:// base URL on a network you trust (a REST proxy). Default false.
baseURL?
Section titled “baseURL?”string
concurrentBuckets?
Section titled “concurrentBuckets?”boolean
Lets requests on a bucket whose limit is known run concurrently, up
to its remaining allowance, instead of one at a time. Requires a
store with reserve. Requests on one bucket may then complete out
of order (e.g. messages to one channel). Defaults to true.
globalLimit?
Section titled “globalLimit?”number | false
Requests per second this bot may send across all buckets,
enforced before Discord answers with a global 429 (shared through
the store, so it holds for every process). Default 50, Discord’s
global limit; set what Discord granted a large bot, or false
to rely on 429s alone.
hooks?
Section titled “hooks?”maxBackoff?
Section titled “maxBackoff?”number
The longest, in ms, that a rate-limit header from the server may
make this client wait. A Retry-After beyond it fails the request
with the 429 instead of sleeping, and stored limits are capped to it,
so a proxy or an attacker cannot stall every request for hours.
Default 600,000 (ten minutes).
maxQueued?
Section titled “maxQueued?”number
Most requests waiting for a bucket slot; more fail with kind "overloaded". Default unlimited.
maxQueuedPerBucket?
Section titled “maxQueuedPerBucket?”number
Most requests waiting on one bucket; more fail with kind "overloaded". Default unlimited.
maxQueueWait?
Section titled “maxQueueWait?”number
Longest, in ms, a request may wait before it is sent (queue,
rate limits, pauses between retries); past it the request fails
with kind "overloaded". Default unlimited. Per request:
maxQueueWait in the request options.
retries?
Section titled “retries?”number
retryPolicy?
Section titled “retryPolicy?”stopOnInvalidToken?
Section titled “stopOnInvalidToken?”boolean
After a 401 on a bot route, refuse every later request with
this token without sending it, until setToken(): repeated 401s
count towards Discord’s invalid-request ban. Default true.
store?
Section titled “store?”telemetry?
Section titled “telemetry?”Receives telemetry events (latency, 429s by scope, waits,
reservations, retries, cancellations, queue depth). See
RESTMetrics for a ready-made aggregator.
timeout?
Section titled “timeout?”number
token?
Section titled “token?”string
transport?
Section titled “transport?”Replaces the HTTP stage, e.g. with a recording transport in tests.
Returns
Section titled “Returns”REST
Throws
Section titled “Throws”If retry configuration is invalid.
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get store():
RateLimitStore
Defined in: packages/rest/src/index.ts:420
The rate-limit store backing this transport.
Returns
Section titled “Returns”Methods
Section titled “Methods”close()
Section titled “close()”close():
Promise<void>
Defined in: packages/rest/src/index.ts:460
Stops the client: new requests are refused, requests still queued or
waiting for a limit fail with kind "aborted", and attempts already
sent are allowed to finish. Resolves when nothing is in flight.
Returns
Section titled “Returns”Promise<void>
delete()
Section titled “delete()”delete<
T>(path,options?):Promise<T>
Defined in: packages/rest/src/index.ts:992
Sends a DELETE request.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
options?
Section titled “options?”Request options (reason, headers, signal, …).
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
diagnostics()
Section titled “diagnostics()”diagnostics():
RESTDiagnostics
Defined in: packages/rest/src/index.ts:437
The client’s current state.
Returns
Section titled “Returns”get<
T>(path,options?):Promise<T>
Defined in: packages/rest/src/index.ts:958
Sends a GET request.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
options?
Section titled “options?”Request options (query, headers, signal, …).
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
patch()
Section titled “patch()”patch<
T>(path,body?,options?):Promise<T>
Defined in: packages/rest/src/index.ts:972
Sends a PATCH request.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
unknown
Optional JSON body.
options?
Section titled “options?”Request options (files, reason, query, headers, signal, …).
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
patchWithFiles()
Section titled “patchWithFiles()”patchWithFiles<
T>(path,payload,files,options?):Promise<T>
Defined in: packages/rest/src/index.ts:1051
Sends a multipart/form-data PATCH request for editing messages with files.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
payload
Section titled “payload”unknown
JSON payload.
Array of file attachments.
options?
Section titled “options?”Cancellation options.
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
post()
Section titled “post()”post<
T>(path,body?,options?):Promise<T>
Defined in: packages/rest/src/index.ts:962
Sends a POST request.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
unknown
Optional JSON body.
options?
Section titled “options?”Request options (files, reason, query, headers, signal, …).
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
postWithFiles()
Section titled “postWithFiles()”postWithFiles<
T>(path,payload,files,options?):Promise<T>
Defined in: packages/rest/src/index.ts:1033
Sends a multipart/form-data POST request for file uploads.
Attaches a JSON payload as payload_json and files as additional fields.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
payload
Section titled “payload”unknown
JSON payload (e.g. message content, embeds).
Array of file attachments.
options?
Section titled “options?”Cancellation options.
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
put<
T>(path,body?,options?):Promise<T>
Defined in: packages/rest/src/index.ts:982
Sends a PUT request.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
API path.
unknown
Optional JSON body.
options?
Section titled “options?”Request options (files, reason, query, headers, signal, …).
Returns
Section titled “Returns”Promise<T>
Decoded response.
Throws
Section titled “Throws”When the request fails.
request()
Section titled “request()”request<
T>(method,path,body?,options?):Promise<T>
Defined in: packages/rest/src/index.ts:496
Executes an HTTP request with Discord bucket/global rate limits, retry handling, and AbortSignal support. Accepts a JSON body, a FormData body (for file uploads), or undefined.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”method
Section titled “method”string
HTTP method.
string
API path.
unknown
Optional JSON body, FormData for file uploads, or undefined.
options?
Section titled “options?”RequestData = {}
Request options: cancellation signal, query, headers,
reason, auth, and files (which upgrade to multipart).
Returns
Section titled “Returns”Promise<T>
Decoded response body.
Throws
Section titled “Throws”If Discord or transport rejects the request.
setHooks()
Section titled “setHooks()”setHooks(
hooks):this
Defined in: packages/rest/src/index.ts:424
Replaces the current hook set. Pass an empty object to clear all hooks.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”this
setToken()
Section titled “setToken()”setToken(
token):void
Defined in: packages/rest/src/index.ts:429
Sets the authentication token.
Parameters
Section titled “Parameters”string
Discord bot token.
Returns
Section titled “Returns”void
Nothing.
Throws
Section titled “Throws”If token is empty.