Rate Limits

All Bot API requests are rate-limited per token using a sliding window algorithm. Stay within limits to avoid 429 responses.

How It Works #

Each bot token has a sliding window per interface. Each request consumes one permit. Permits replenish as the window slides forward in time.

Permit limit — maximum number of requests allowed within the sliding window. Smoothed across 6 segments for even distribution.

Window — the time period over which requests are counted. Permits become available as older segments slide out.

Concurrency — a global limit of 10 concurrent requests per bot prevents parallel flooding, independent of per-interface limits.

Per-Interface Limits #

Each interface has its own sliding window. Limits are enforced independently per bot token.

Interface Limit Window

IArchetypes 30 req 1m

IBotSelf 15 req 1m

ICalls 20 req 1m

IChannels 60 req 1m

ICommands 60 req 1m

IEvents 5 req 1m

IExpressions 60 req 1m

IFiles 30 req 1m

IInteractions 120 req 1m

IMembers 30 req 1m

IMessages 120 req 1m

IReactions 60 req 1m

ISpaces 30 req 1m

ITyping 60 req 1m

IVoice 20 req 1m

IVoiceEgress 10 req 1m

Handling 429 Responses #

When a bucket is empty, the server returns 429 Too Many Requests.

HTTP/1.1 429 Too Many Requests
Retry-After: 4
X-RateLimit-Remaining: 0

{
  "error": "rate_limited",
  "retry_after": 3.2,
  "message": "You are being rate limited."
}

Check the Retry-After header — it tells you how many seconds to wait before retrying.

Use exponential backoff — if you're consistently hitting limits, increase the delay between requests exponentially.

Queue non-urgent work — batch operations when possible instead of sending many small requests.

Space Budget for Stickers & Emoji #

Sticker and custom emoji work has a second limit on top of the IExpressions (60/min) and IFiles (30/min) windows above. Each space allows 120 changes per minute from all bots together — a budget kept apart from the people's, so bots and members never starve each other. Past it, a change returns 429 with its own code:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "space_rate_limited",
  "message": "The bots' budget for sticker and emoji changes in this space is spent for the minute; see Retry-After."
}

rate_limited space_rate_limited

Counts Every request of one bot to one interface, in every space Changes by every bot in one space

Window Sliding, per the table above Fixed: a minute from the first change; once spent, a minute from the first refusal

Retry-After Seconds until a permit frees up Always 60 — the budget is back at the latest a minute after the refusal

What counts as a change — CreatePack, UpdatePack, AddItem and UpdateItem. Reads never count, and neither do a repeated CreatePack that returns the bot's existing pack or an update that changes nothing. An AddItem refused for its file (invalid_format, too_large, content_rejected) has already counted. Branch on the error code, not the status: both limits answer 429, and both are waited out the same way. See Stickers & Custom Emoji.

Request Size #

Routes that take files also cap the body. Past the cap the server answers 413 too_large.

Route Body Largest file

IFiles/Upload ≈ 10 MiB 10 MiB for an attachment; 4 MiB for a sticker or emoji file.

IMessages/Send ≈ 10 MiB 10 MiB; the parts of one multipart request share the body. Larger sets go through IFiles/Upload first.

IExpressions/AddItem 5 MiB By format — see Formats & Limits.

≈ 10 MiB is 10 MiB of file plus 256 KiB for the form around it.

Verified Bot Limits #

Verified bots receive higher rate limits automatically. There is no separate API — once your bot is verified, limits are increased server-side.