Tokens, rate limits and errors
Tokens
Every REST request carries the token in the Authorization header:
Authorization: Bot <token>
A token looks like Discord's: three parts separated by dots, the first being the bot's id
in base64. A missing or wrong token gets 401 with
{ "message": "401: Unauthorized", "code": 0 }. The gateway takes the token
in Identify, with or without Bot in front.
GET /gateway is the only endpoint that works without a token. There are no
user tokens. OAuth2 bearer tokens, from Login with
Voicaw, only open GET /users/@me and GET /oauth2/@me: the
rest of the bot API is for bots only.
Rate limits
Each bot may make 50 requests a second in all. On top of that, routes have their own limits, counted per bot and per channel or guild:
| Route | Limit |
|---|---|
| Send a message | 5 per 5 s, per channel |
| Edit a message | 5 per 5 s, per channel |
| Delete a message | 5 per second, per channel |
| Bulk delete | 1 per second, per channel |
| Get messages | 10 per second, per channel |
| Add or remove reactions | 4 per second, per channel |
| Pin or unpin | 5 per 5 s, per channel |
| Typing | 5 per 5 s, per channel |
| Start a thread | 5 per 5 s, per channel |
| Create an invite | 5 per 5 s, per channel |
| Edit or delete a channel | 5 per 10 s, per channel |
| Set or remove a permission overwrite | 10 per 10 s, per channel |
| Create a channel | 5 per 5 s, per guild |
| Create, edit or move roles | 5 per 5 s, per guild (each) |
| Edit a member, add or remove a member's role | 10 per 10 s, per guild (each) |
| Kick | 5 per 5 s, per guild |
| Ban or unban | 5 per 5 s, per guild |
| Change the bot's name or picture | 2 per hour |
Limited routes answer with Discord's headers, so libraries pace themselves:
X-RateLimit-Limit, X-RateLimit-Remaining,
X-RateLimit-Reset, X-RateLimit-Reset-After and
X-RateLimit-Bucket. Over a limit, you get 429 with a
Retry-After header and:
{ "message": "You are being rate limited.", "retry_after": 1.234, "global": false, "code": 0 }
X-RateLimit-Scope is user for a route's limit, or
global (with X-RateLimit-Global: true) for the 50 a second. The
gateway has its own limit: see Gateway.
Errors
Errors are Discord's shape (plus error, the same text):
{ "message": "Missing Permissions", "code": 50013 }
{
"message": "Invalid Form Body",
"code": 50035,
"errors": { "embeds": { "0": { "title": { "_errors": [{ "code": "BASE_TYPE_MAX_LENGTH", "message": "Must be 256 or fewer in length." }] } } } }
}The codes you can get:
| Code | Meaning |
|---|---|
0 | Unauthorized (401), Not Found for an unknown route (404), or rate limited (429) |
10003 | Unknown Channel (also a channel the bot can't see) |
10004 | Unknown Guild (also a guild the bot isn't in) |
10007 | Unknown Member |
10008 | Unknown Message |
10011 | Unknown Role |
10013 | Unknown User (also anyone the bot shares no guild with) |
10014 | Unknown Emoji |
10026 | Unknown Ban |
30003 | Too many pinned messages (250 per channel) |
30010 | Too many reactions (20 per bot per message) |
40005 | Request too large (files: 10 at most, 25 MB together; JSON: 1 MB) |
50003 | Cannot execute action on a DM channel (reactions, pins, threads… in a DM, or deleting the person's message) |
50005 | Cannot edit a message authored by another user |
50006 | Cannot send an empty message |
50007 | Cannot send messages to this user (no shared guild, blocked, or they turned bot DMs off) |
50013 | Missing Permissions, or ranked too low (roles and members above the bot's highest role) |
50021 | Cannot execute action on a system message |
50024 | Cannot execute action on this channel type |
50035 | Invalid Form Body (with errors saying which field), or a request Voicaw refuses |
50109 | The request body isn't valid JSON |
160004 | That message already has a thread |
A channel, guild or user the bot isn't allowed to see answers as if it didn't exist (404), not with Missing Access.