discord-api

discord-api Best Practices

Building Discord applications requires adherence to specific patterns for reliability and compliance. This guide outlines the essential practices for our team.

1. API Interaction: REST First, Gateway for Events

Always prefer the HTTP REST API for creating, updating, or deleting resources. The Gateway is exclusively for receiving real-time events. This minimizes rate-limit issues and simplifies scaling.

❌ BAD: Using Gateway for resource modification

// Don't send messages or modify roles via Gateway opcodes directly
// This is an oversimplification, but illustrates the anti-pattern
gateway.send({ op: GatewayOpcodes.MessageCreate, d: { channel_id: '...', content: '...' } });

✅ GOOD: Using REST for resource modification

import { Routes, REST } from 'discord-api-types/v10';

const rest = new REST().setToken(process.env.DISCORD_BOT_TOKEN!);

// Always specify the API version (v10 as of 2025)
await rest.post(Routes.channelMessages('12345'), {
  body: { content: 'Hello via REST!' },
});

2. Strong Typing with discord-api-types

Ensure all API payloads conform to Discord's official types. This prevents runtime errors and future-proofs against API changes.

❌ BAD: Untyped payloads

// Prone to typos and API changes breaking at runtime
const messagePayload = {
  channel_id: '123',
  content: 'Untyped message',
};

✅ GOOD: Typed payloads

import { APIChannel, APIMessage } from 'discord-api-types/v10';

const channel: APIChannel = await rest.get(Routes.channel('123'));
const messagePayload: APIMessage = {
  channel_id: channel.id,
  content: 'Typed message!',
  // ... other required fields
};

3. Rate Limit Handling: Exponential Back-off

Discord's API is heavily rate-limited. Implement robust exponential back-off with jitter to handle 429 Too Many Requests responses gracefully.

❌ BAD: Ignoring rate limits or simple retries

try {
  await rest.post(Routes.channelMessages('...'), { body: { content: '...' } });
} catch (error: any) {
  if (error.status === 429) {
    console.warn('Rate limited! Retrying immediately...');
    await rest.post(Routes.channelMessages('...'), { body: { content: '...' } }); // Will likely fail again
  }
}