Skip to content

REST & Rate Limits

lunibee (rest) provides a type-safe HTTP client specifically tuned for Discord API v10.

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 Requests global limit is encountered.
import { REST, Routes } from "lunibee";
const rest = new REST({ token: process.env.DISCORD_TOKEN! });
// Fetch current bot user
const me = await rest.get(Routes.user());
// Send a message
const message = await rest.post(Routes.channelMessages("123456789012345678"), {
body: {
content: "Hello from Lunibee REST!",
},
});

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);
}

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.

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
}
}