So your bot is rate limited...

You wrote a bot, it got popular... and now it's lagging because you are getting 429 errors and being rate limited. It happens. Follow this guide, and you should get your bot working again in no time.

Slow Mode

Note, in some groups, the admins may have enabled slow mode. In this case, if your bot attempts to send messages within the time designated by admins, you will receive a 429 error, with a retry_after parameter telling you how long to wait:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 9",
  "parameters": {
    "retry_after": 9
  }
}

If you get a 429 when sending a message, you can also try calling getChat, and checking for the slow_mode_delay property.

Limits

First, let's discuss the limits you should be paying attention to, which can be found in the Bot FAQ.

When sending messages inside a particular chat, avoid sending more than one message per second. We may allow short bursts that go over this limit, but eventually you'll begin receiving 429 errors.

What this is saying is that per chat you should avoid sending more than 1 message per second. Keep in mind, a chat is a user, channel, group, or supergroup.

If you're sending bulk notifications to multiple users, the API will not allow more than 30 messages per second or so. Consider spreading out notifications over large intervals of 8—12 hours for best results.

This part is pretty clear. You can send ~30 messages in one second, but remember the first part - that's to 30 different chats, not to the same chat.

Also note that your bot will not be able to send more than 20 messages per minute to the same group.

Again, this is per chat. You can send 20 messages a minute to group A, and 20 messages in a minute to supergroup B.

Keep in mind - if you hit rate limits anywhere (even just in one group) - your bot will get 429 errors, no matter what the message. I.e. if you hit rate limits in group A, you won't be able to message User 2 for a moment.

Other Limits

What other limits are there you should be aware of? A big one is the large message limit. Any message that is greater than 512 bytes (currently, this is subject to change, as are all things in the bot API) in size is considered a large message, as this affects people on mobile phones who may have a data cap. Keep in mind, the size is the final text sent, but with some exceptions.

Examples:

This message is 22 bytes. There is no formatting of any kind, nice and simple.

This is a test message

This message is 66 bytes, but the output looks like "this is a link parsed with HTML" which is only 31 bytes, so count it as 31 bytes.

this is a <a href="https://t.me/BotTalk">link</a> parsed with html

This message contains newlines, which are 1 byte but will be counted as 5, so this will be counted as 19 bytes.

t\ne\ns\nt

Some other symbols such as & or " may also be counted as 5 or 6 bytes.

Also, keep in mind emoji have high byte sizes - a simple smiley face emoji is 4 bytes by itself!

To do a quick test on byte sizes of strings, check out this site.

But what does this all mean? Large messages have a special limit. From testing, it appears that you can send 4 large messages per minute to a single ID. I've always considered that as meaning 1 large message = 5 regular messages, so keep that in mind.

Spam

That's great and all, but my users keep spamming commands! They are ruining my bot!

Don't despair. You just need to pass the rate limits on to your users. There are a few things you can do to keep them in check.

- Use a queue for groups

On one of my bots, I use a queue in group chats. The way it works is when the bot needs to send a message to that group, it puts it in the queue. Then once every 4 seconds (remember, 20 messages per minute? 60/20 = 3, but I use 4 just to be safe), the bot starts working the queue. It takes each message from the top, appends it to one large message.

However, remember the large message sizes we talked about? With each message, it checks the final size of the message - if it's over 512 bytes, I've added too many messages. Put that last one back on the top of the queue, and send the grouped messages as one. Wait 4 seconds, repeat.

If the top message in the queue is already > 512 bytes, then send it and wait 10 seconds.

- Rate limit individual users

Rate limiting users isn't exactly needed (unless they use a userbot to spam your bot >30 times a second.... I've had this happen before, or they are spamming in a group), but still, it's a good idea, to save on CPU time/resources on your server.

There are a couple of ways you can do this. For one, keep a small log of messages received from a single user (but, only count messages that would cause your bot to reply!). I just keep a simple array of timestamps per user (or you could use a `Dictionary<int, DateTime[]>`). Each time the user sends a message, I added another timestamp to the array, remove any timestamps that are more than a minute old, then check the size of the array. More than 20 messages? User is going to get the bot rate-limited, so ignore their message.

I typically warn the user once they hit 10 and let them know that I'm about to start ignoring them, "calm down". If they continue to spam the bot, I "ban" them temporarily. I.e. my bot will ignore ALL commands from them for some time. I typically use 6 hours, 12 hours, 24 hours, 48 hours, permanent, increasing with each time they spam the bot. (the bot does issue a warning, telling the user they will be ignored for the time).

Another solution I've used is simply don't even allow them to use more than 1 command every 4 seconds. (this will also save memory your bot uses, by removing the per user array). In this instance, I simply keep a key-value pair or userid & timestamp. If the users' last message was within 4 seconds, ignore. (Don't replace the key-value pair, just let the 4 seconds go by). If it was more than 4 seconds ago, replace the timestamp and reply to them. Just like that, users cannot make your bot hit rate limits in PM even if they wanted to.

So - in groups, use a queue, send a message once every 4 seconds, grouping any messages together. In a private chat, simply ignore them if they spam, and only respond to commands once every 4 seconds.

Here is a handy list of values you can use in any rate-limiting code you have.

MAX_CAPTION_LENGTH = 1024

MAX_FILESIZE_DOWNLOAD = 20000000

MAX_FILESIZE_UPLOAD = 50000000

MAX_MESSAGES_PER_MINUTE_PER_GROUP = 20

MAX_MESSAGES_PER_SECOND = 30

MAX_MESSAGES_PER_SECOND_PER_CHAT = 1

MAX_MESSAGE_LENGTH = 4096

MAX_MESSAGE_LENGTH_IN_GRAPH = 65536