Skip to content

REST

Defined in: packages/rest/src/index.ts:287

Bun-native REST transport with Discord bucket-aware rate limiting, retries, and cancellation.

new REST(options?): REST

Defined in: packages/rest/src/index.ts:317

Creates a REST transport.

Transport configuration.

boolean

Allow a cleartext http:// base URL on a network you trust (a REST proxy). Default false.

string

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.

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.

RESTHooks

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).

number

Most requests waiting for a bucket slot; more fail with kind "overloaded". Default unlimited.

number

Most requests waiting on one bucket; more fail with kind "overloaded". Default unlimited.

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.

number

RetryPolicy

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.

RateLimitStore

RESTTelemetry

Receives telemetry events (latency, 429s by scope, waits, reservations, retries, cancellations, queue depth). See RESTMetrics for a ready-made aggregator.

number

string

HttpTransport

Replaces the HTTP stage, e.g. with a recording transport in tests.

REST

If retry configuration is invalid.

get store(): RateLimitStore

Defined in: packages/rest/src/index.ts:420

The rate-limit store backing this transport.

RateLimitStore

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.

Promise<void>


delete<T>(path, options?): Promise<T>

Defined in: packages/rest/src/index.ts:992

Sends a DELETE request.

T

string

API path.

RequestData

Request options (reason, headers, signal, …).

Promise<T>

Decoded response.

When the request fails.


diagnostics(): RESTDiagnostics

Defined in: packages/rest/src/index.ts:437

The client’s current state.

RESTDiagnostics


get<T>(path, options?): Promise<T>

Defined in: packages/rest/src/index.ts:958

Sends a GET request.

T

string

API path.

RequestData

Request options (query, headers, signal, …).

Promise<T>

Decoded response.

When the request fails.


patch<T>(path, body?, options?): Promise<T>

Defined in: packages/rest/src/index.ts:972

Sends a PATCH request.

T

string

API path.

unknown

Optional JSON body.

RequestData

Request options (files, reason, query, headers, signal, …).

Promise<T>

Decoded response.

When the request fails.


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.

T

string

API path.

unknown

JSON payload.

RESTFileAttachment[]

Array of file attachments.

RESTRequestOptions

Cancellation options.

Promise<T>

Decoded response.

When the request fails.


post<T>(path, body?, options?): Promise<T>

Defined in: packages/rest/src/index.ts:962

Sends a POST request.

T

string

API path.

unknown

Optional JSON body.

RequestData

Request options (files, reason, query, headers, signal, …).

Promise<T>

Decoded response.

When the request fails.


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.

T

string

API path.

unknown

JSON payload (e.g. message content, embeds).

RESTFileAttachment[]

Array of file attachments.

RESTRequestOptions

Cancellation options.

Promise<T>

Decoded response.

When the request fails.


put<T>(path, body?, options?): Promise<T>

Defined in: packages/rest/src/index.ts:982

Sends a PUT request.

T

string

API path.

unknown

Optional JSON body.

RequestData

Request options (files, reason, query, headers, signal, …).

Promise<T>

Decoded response.

When the request fails.


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.

T

string

HTTP method.

string

API path.

unknown

Optional JSON body, FormData for file uploads, or undefined.

RequestData = {}

Request options: cancellation signal, query, headers, reason, auth, and files (which upgrade to multipart).

Promise<T>

Decoded response body.

If Discord or transport rejects the request.


setHooks(hooks): this

Defined in: packages/rest/src/index.ts:424

Replaces the current hook set. Pass an empty object to clear all hooks.

RESTHooks

this


setToken(token): void

Defined in: packages/rest/src/index.ts:429

Sets the authentication token.

string

Discord bot token.

void

Nothing.

If token is empty.