Rate limits

Every account has a bucket per action. A bucket holds burst requests, and refills at its rate, in requests a second. A request that finds its bucket empty is refused with RATE_LIMITED before anything is done. A bot is an account, so it has buckets of its own, separate from its owner's.

What the library does about it

illest.py keeps the same buckets on its side and waits for a token before it sends, so a bot that sends in a loop is slowed, not refused. The two can still disagree (another copy of the bot running on the same account, or a restart with full buckets on the bot's side and empty ones on the server's). A refused request is sent again after the time its bucket needs, three times, and only then raised:

import illest


async def announce(channel: illest.TextChannel, text: str):
    try:
        await channel.send(text)
    except illest.RateLimited as error:
        print(f"try again in {error.retry_after} seconds")

retry_after is the server's figure when it gave one, otherwise the action's published rate.

The limits

Every action a bot may send, with its bucket. An action without a limit of its own takes the default, 10 at once, then 2 a second. The library is built against these numbers; a server that changes them is waited out by the retry.

Being a good citizen

• Send one message with several lines rather than several messages.
• Edit a status message rather than posting a new one each minute.
• A task that runs on a timer (ext.tasks.loop) should run as often as its answer changes, and no more.