REST & Rate Limits
lunibee (rest) provides a type-safe HTTP client specifically tuned for Discord API v10.
Bucket-Aware Rate Limiting
Section titled “Bucket-Aware Rate Limiting”Discord groups routes into rate-limit buckets. lunibee (rest) tracks bucket headers (X-RateLimit-Bucket, X-RateLimit-Remaining, X-RateLimit-Reset-After) on every response.
- Non-blocking queues: Requests targeting different buckets execute concurrently.
- Sublimit protection: Requests waiting on a shared bucket automatically pause until the bucket resets.
- Global rate limits: Pauses all REST queues transparently if a
429 Too Many Requestsglobal limit is encountered.
Example Requests
Section titled “Example Requests”import { REST, Routes } from "lunibee";const rest = new REST({ token: process.env.DISCORD_TOKEN! });// Fetch current bot userconst me = await rest.get(Routes.user());// Send a messageconst message = await rest.post(Routes.channelMessages("123456789012345678"), { body: { content: "Hello from Lunibee REST!", },});import { REST, Routes } from "lunibee";const rest = new REST({ token: process.env.DISCORD_TOKEN });// Fetch current bot userconst me = await rest.get(Routes.user());// Send a messageconst message = await rest.post(Routes.channelMessages("123456789012345678"), { body: { content: "Hello from Lunibee REST!", },});AbortSignal Support & Cancellation
Section titled “AbortSignal Support & Cancellation”Every REST method accepts request options (query, headers, reason, signal, …), including an AbortSignal. Cancellation and timeouts reject with a RESTError whose kind is "aborted" or "timeout":
import { RESTError } from "lunibee";
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);
try { const result = await rest.get(Routes.guild("123456789012345678"), { signal: controller.signal, });} catch (error) { if (error instanceof RESTError && (error.kind === "aborted" || error.kind === "timeout")) { console.warn("Request timed out or was cancelled."); }} finally { clearTimeout(timeout);}import { RESTError } from "lunibee";
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);
try { const result = await rest.get(Routes.guild("123456789012345678"), { signal: controller.signal, });} catch (error) { if (error instanceof RESTError && (error.kind === "aborted" || error.kind === "timeout")) { console.warn("Request timed out or was cancelled."); }} finally { clearTimeout(timeout);}Concurrent Buckets
Section titled “Concurrent Buckets”Since 0.3.1, requests on a rate-limit bucket whose limit is already known run in parallel, up to its remaining allowance. Before that they ran one at a time, which keeps their order (messages to one channel arrive in the order you sent them). Pass concurrentBuckets: false to get that back:
const ordered = new REST({ token, concurrentBuckets: false });A 10,000-request soak test across 20 shared buckets (tests/rest.soak.test.ts) stays under 1% rate-limited.
- A bucket whose limit is not known yet still sends one request (the probe) until a response reveals it — across every process sharing the store.
- Requests on one bucket may finish out of order.
- Needs a rate-limit store with atomic
reserve(). The default memory store and the Redis store have one.
Several processes or bots sharing limits through Redis: see Distributed REST.
Classifying Failures
Section titled “Classifying Failures”Every RESTError has a kind and a retryable flag, so handlers do not need
to match status codes:
import { RESTError } from "lunibee";
try { await client.channels.send(channelId, { content: "hi" });} catch (error) { if (error instanceof RESTError) { error.kind; // "permission" | "notFound" | "validation" | "rateLimited" | "server" | "timeout" | ... error.retryable; // true for rateLimited, server, network, timeout, coordination and overloaded }}