Handle Rate Limits

This guide explains how to detect and handle rate limit errors when making requests with the Discord Social SDK.

When an SDK operation is rate limited, the callback receives a failed ClientResult where ClientResult::Retryable is true and ClientResult::RetryAfter contains the number of seconds to wait before retrying.

Every SDK operation that makes a network request passes a ClientResult to its callback. Always check ClientResult::Successful first. If the operation failed, inspect ClientResult::Retryable to decide whether to retry:

client->SendLobbyMessage(lobbyId, message, [](discordpp::ClientResult result, uint64_t messageId) {
  if (result.Successful()) {
    return;
  }

  if (result.Retryable()) {
    float delaySeconds = result.RetryAfter();
    // Schedule a retry after delaySeconds — see below
  } else {
    std::cerr << "Unrecoverable error: " << result.ToString() << "\n";
  }
});

ClientResult::Retryable is set for rate limit responses (HTTP 429) as well as transient network errors. It is false for permission errors, validation failures, and other non-recoverable failures — don't retry those.

Use ClientResult::RetryAfter as the minimum delay before your next attempt. Retrying before this elapses will trigger continued rate limiting.

A simple retry helper using your game engine's timer system:

void SendMessageWithRetry(
    std::shared_ptr<discordpp::Client> client,
    uint64_t lobbyId,
    std::string message,
    int attemptsLeft)
{
  client->SendLobbyMessage(lobbyId, message,
    [client, lobbyId, message, attemptsLeft](discordpp::ClientResult result, uint64_t messageId) {
      if (result.Successful()) {
        std::cout << "Message sent\n";
        return;
      }

      if (result.Retryable() && attemptsLeft > 1) {
        float delay = result.RetryAfter();
        ScheduleCallback(delay, [client, lobbyId, message, attemptsLeft]() {
          SendMessageWithRetry(client, lobbyId, message, attemptsLeft - 1);
        });
      } else {
        std::cerr << "Failed after retries: " << result.ToString() << "\n";
      }
    });
}

ScheduleCallback here represents whatever timer mechanism your engine provides (e.g. a delayed task queue, coroutine sleep, or engine tick callback).

For more information on rate limits and how to apply for increased limits for production releases, see Communication Features. For general information on how Discord rate limiting works, see Discord's rate limiting documentation.

Need help? Join the Discord Developers Server and share questions in the #social-sdk-dev-help channel for support from the community.

If you encounter a bug while working with the Social SDK, please report it here: https://dis.gd/social-sdk-bug-report