Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Moderation and Security

Rate Limits, Retries and Backoff

Handle Discord and Telegram rate limits correctly: read 429 responses and retry_after, add exponential backoff with jitter, and queue outgoing calls with a token bucket.

Both platforms protect themselves with rate limits, and a bot that ignores them gets slowed down, throttled, or in bad cases banned. Limits are not a rare edge case. Announce something to a busy channel, loop over members, or reply to a flood of commands and you will hit them. This lesson shows what the limits look like, how to react to a 429 Too Many Requests, and how to avoid triggering them in the first place.

Exact numbers change over time and differ by method, so treat the figures below as orders of magnitude and always trust the response headers and bodies over any table.

What the platforms tell you

Telegram documents rough limits: about one message per second in a single chat (with short bursts allowed), about 20 messages per minute in one group, and around 30 messages per second across all chats when broadcasting. When you go over, the API replies with HTTP 429 and a JSON body that includes parameters.retry_after, the number of seconds to wait.

Discord replies to every REST call with headers describing your bucket: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset-After and X-RateLimit-Bucket. A 429 response carries a JSON body with retry_after (seconds, possibly fractional) and a global flag. There is also a global limit of about 50 requests per second per bot, and an invalid-request limit: too many 401, 403 or 429 responses in a short time from one IP can get that IP temporarily blocked by Cloudflare. That is why retrying blindly in a tight loop is dangerous.

Rule 1: obey retry_after

The server tells you exactly how long to wait. Wait that long (plus a little), then retry the same request once.

Node.js A client that honors retry_after

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Cap the retries. A request that is rejected five times in a row is a bug in your code, not bad luck.

Rule 2: exponential backoff with jitter for everything else

Network errors and 5xx responses have no retry_after. Retry them with growing delays: 1 s, 2 s, 4 s, 8 s, and so on up to a ceiling. Add randomness ("jitter") so that a hundred bots that failed at the same moment do not all retry at the same moment, which would just recreate the overload.

Node.js Backoff delays with full jitter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Only retry what is safe to retry. A failed sendMessage might still have been delivered; retrying can post twice. For actions like kicking a member, a second attempt is harmless, but for "send 100 coins" you need an idempotency check in your own database. Do not retry 4xx errors other than 429: a 400 or 403 will fail the same way again.

Rule 3: do not hit the limit at all

Reacting to 429 is the fallback. A well-behaved bot paces itself. A token bucket does that: the bucket holds up to N tokens, refills at a fixed rate, and each request takes one token. When the bucket is empty, requests wait.

Node.js A token bucket queue for outgoing messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Three ideas to carry into real bots:

  • Keep one bucket per chat or channel and one global bucket for the whole bot.
  • Put outgoing calls in a queue so the rest of your code never sleeps; a worker takes from the queue at the permitted rate.
  • Prefer fewer, richer messages: one message with a list beats ten messages. Telegram lets you edit a message instead of sending a new one; Discord lets you edit an embed. Both save quota.

Broadcasting safely

Sending an announcement to every user is the classic way to get throttled. Spread it out: about 20 to 25 messages per second for Telegram broadcasts, honor every retry_after, and remove users who return 403 Forbidden: bot was blocked by the user from your list so you stop trying. On Discord, avoid per-member DMs in bulk; Discord treats mass DMs as abuse and may flag the bot.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A Telegram 429 response contains parameters.retry_after = 5. What should the bot do?

    retry_after is the platform's instruction for how long to wait.
  2. 2. What is the purpose of jitter in backoff?

    Without jitter, clients that failed together retry together and overload the service again.
  3. 3. Which error should normally NOT be retried?

    A request that is invalid will be invalid again. Retry transient failures and rate limits only.
  4. 4. How does a token bucket keep a bot under a limit?

    It allows short bursts up to the capacity but enforces the long-run rate.

Summary

  • Read 429 bodies and headers; obey retry_after exactly, with a retry cap.
  • Use exponential backoff with jitter for network errors and 5xx; never retry bad requests.
  • Pace outgoing calls with token buckets per chat and a global one, and queue sends.
  • Broadcast slowly, handle blocked users, and combine or edit messages to save quota.

Next: Moderation commands and permissions