Rate limits

Rate limiting is a fixed window:

• Each named bucket allows a set number of calls.
• Anything past that returns 429 Too Many Requests.
• A bucket refills ten seconds after the first request that filled it.

Buckets are independent. Exhausting one does not affect any other, so a client hammering message sends does not lose its ability to fetch a channel.

Buckets

Method	Path	Limit
	/users	20
PATCH	/users/:id	2
	/users/:id/default_avatar	255
	/bots	10
	/channels	15
POST	/channels/:id/messages	10
	/servers	5
	/auth	3
DELETE	/auth	255
	/safety	15
	/safety/report	3
	/swagger	100
	/*	20

Headers

Every response carries enough to stay under the limit without guessing.

Header	Type	Description
X-RateLimit-Limit	number	Calls allowed for this bucket
X-RateLimit-Bucket	string	Identifier of the bucket that was charged
X-RateLimit-Remaining	number	Calls left in it
X-RateLimit-Reset-After	number	Milliseconds until it refills

Read X-RateLimit-Bucket rather than inferring which bucket a route belongs to from its path — the mapping is a server-side decision and may change.

Being limited

A 429 carries a body saying how long to wait:

interface Response {
  // Milliseconds until calls are replenished
  retry_after: number;
}

Wait for retry_after rather than retrying on a timer of your own. Retrying sooner does not make the window shorter; it just spends the next one.