Rate Limits

Understand discord.place API rate limits to avoid 429 errors.

The discord.place API enforces rate limits on all endpoints to ensure fair usage for every developer. When you exceed your allowance, the API returns a 429 Too Many Requests response.

Response Headers

Every API response includes the following headers so you can track your current rate-limit window:

ratelimit-limit · integer · required

The maximum number of requests allowed in the current window.

Example: 10

ratelimit-remaining · integer · required

The number of requests remaining in the current window.

Example: 9

ratelimit-reset · integer · required

Time in seconds until the rate-limit window resets and your allowance is restored.

Example: 60

429 Response Body

When you exceed the limit, the API responds with:

{
  "success": false,
  "error": "Too many requests, please try again later.",
  "status": 429
}

Handling Rate Limits

Read the ratelimit-remaining header on every response. When it reaches 0, pause requests until ratelimit-reset seconds have elapsed rather than waiting for a 429 error.

If you do receive a 429, implement exponential backoff before retrying:

async function fetchWithBackoff(url, options, retries = 4) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    const resetAfter = parseInt(response.headers.get('ratelimit-reset') ?? '1', 10);
    // Wait for the window to reset, then add jitter for subsequent retries
    const delay = (resetAfter * 1000) + (attempt * 500);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Rate limit retries exhausted');
}

Per-Endpoint Limits

Rate limits are applied per endpoint. The limits currently in effect are:

Endpoint	Limit
PATCH /bots/{id}/stats	2 requests per 120 minutes
GET /bots/{id}/voters/{user_id}	100 requests per 5 minutes

The PATCH /bots/{id}/stats limit is intentionally low. Call this endpoint on a timer (e.g., every hour) rather than on every guild event to stay well within the window.

Requesting a Rate Limit Exemption

If your use case requires higher throughput than the default limits allow, contact the discord.place team at [e-mail] or reach out on the Discord server to discuss a whitelisting arrangement.