Opcodes and Status Codes

Gateway

All gateway events in Discord are tagged with an opcode that denotes the payload type. Your connection to our gateway may also sometimes close. When it does, you will receive a close code that tells you what happened.

Gateway Opcodes

Code	Name	Client Action	Description
0	Dispatch	Receive	An event was dispatched.
1	Heartbeat	Send/Receive	Fired periodically by the client to keep the connection alive.
2	Identify	Send	Starts a new session during the initial handshake.
3	Presence Update	Send	Update the client’s presence.
4	Voice State Update	Send	Used to join/leave or move between voice channels.
6	Resume	Send	Resume a previous session that was disconnected.
7	Reconnect	Receive	You should attempt to reconnect and resume immediately.
8	Request Guild Members	Send	Request information about offline guild members in a large guild.
9	Invalid Session	Receive	The session has been invalidated. You should reconnect and identify/resume accordingly.
10	Hello	Receive	Sent immediately after connecting, contains the heartbeat_interval to use.
11	Heartbeat ACK	Receive	Sent in response to receiving a heartbeat to acknowledge that it has been received.
31	Request Soundboard Sounds	Send	Request information about soundboard sounds in a set of guilds.
43	Request Channel Info	Send	Request ephemeral channel data for channels in a guild.

Gateway Close Event Codes

In order to prevent broken reconnect loops, you should consider some close codes as a signal to stop reconnecting. This can be because your token expired, or your identification is invalid. This table explains what the application defined close codes for the gateway are, and which close codes you should not attempt to reconnect.

Code	Description	Explanation	Reconnect
4000	Unknown error	We’re not sure what went wrong. Try reconnecting?	true
4001	Unknown opcode	You sent an invalid Gateway opcode or an invalid payload for an opcode. Don’t do that!	true
4002	Decode error	You sent an invalid payload to Discord. Don’t do that!	true
4003	Not authenticated	You sent us a payload prior to identifying, or this session has been invalidated.	true
4004	Authentication failed	The account token sent with your identify payload is incorrect.	false
4005	Already authenticated	You sent more than one identify payload. Don’t do that!	true
4007	Invalid seq	The sequence sent when resuming the session was invalid. Reconnect and start a new session.	true
4008	Rate limited	Woah nelly! You’re sending payloads to us too quickly. Slow it down! You will be disconnected on receiving this.	true
4009	Session timed out	Your session timed out. Reconnect and start a new one.	true
4010	Invalid shard	You sent us an invalid shard when identifying.	false
4011	Sharding required	The session would have handled too many guilds - you are required to shard your connection in order to connect.	false
4012	Invalid API version	You sent an invalid version for the gateway.	false
4013	Invalid intent(s)	You sent an invalid intent for a Gateway Intent. You may have incorrectly calculated the bitwise value.	false
4014	Disallowed intent(s)	You sent a disallowed intent for a Gateway Intent. You may have tried to specify an intent that you have not enabled or are not approved for.	false

Voice

Our voice gateways have their own set of opcodes and close codes.

Voice Opcodes

Code	Name	Sent By	Description	Binary
0	Identify	client	Begin a voice websocket connection.
1	Select Protocol	client	Select the voice protocol.
2	Ready	server	Complete the websocket handshake.
3	Heartbeat	client	Keep the websocket connection alive.
4	Session Description	server	Describe the session.
5	Speaking	client and server	Indicate which users are speaking.
6	Heartbeat ACK	server	Sent to acknowledge a received client heartbeat.
7	Resume	client	Resume a connection.
8	Hello	server	Time to wait between sending heartbeats in milliseconds.
9	Resumed	server	Acknowledge a successful session resume.
11	Clients Connect	server	One or more clients have connected to the voice channel
13	Client Disconnect	server	A client has disconnected from the voice channel
21	DAVE Prepare Transition	server	A downgrade from the DAVE protocol is upcoming
22	DAVE Execute Transition	server	Execute a previously announced protocol transition
23	DAVE Transition Ready	client	Acknowledge readiness previously announced transition
24	DAVE Prepare Epoch	server	A DAVE protocol version or group change is upcoming
25	DAVE MLS External Sender	server	Credential and public key for MLS external sender	X
26	DAVE MLS Key Package	client	MLS Key Package for pending group member	X
27	DAVE MLS Proposals	server	MLS Proposals to be appended or revoked	X
28	DAVE MLS Commit Welcome	client	MLS Commit with optional MLS Welcome messages	X
29	DAVE MLS Announce Commit Transition	server	MLS Commit to be processed for upcoming transition	X
30	DAVE MLS Welcome	server	MLS Welcome to group for upcoming transition	X
31	DAVE MLS Invalid Commit Welcome	client	Flag invalid commit or welcome, request re-add

Voice Close Event Codes

Code	Description	Explanation
4001	Unknown opcode	You sent an invalid opcode.
4002	Failed to decode payload	You sent an invalid payload in your identifying to the Gateway.
4003	Not authenticated	You sent a payload before identifying with the Gateway.
4004	Authentication failed	The token you sent in your identify payload is incorrect.
4005	Already authenticated	You sent more than one identify payload. Stahp.
4006	Session no longer valid	Your session is no longer valid.
4009	Session timeout	Your session has timed out.
4011	Server not found	We can’t find the server you’re trying to connect to.
4012	Unknown protocol	We didn’t recognize the protocol you sent.
4014	Disconnected	Disconnect individual client (you were kicked, the main gateway session was dropped, etc.). Should not reconnect.
4015	Voice server crashed	The server crashed. Our bad! Try resuming.
4016	Unknown encryption mode	We didn’t recognize your encryption.
4017	E2EE/DAVE protocol required	This channel requires a client supporting E2EE via the DAVE Protocol
4020	Bad request	You sent a malformed request
4021	Disconnected: Rate Limited	Disconnect due to rate limit exceeded. Should not reconnect.
4022	Disconnected: Call Terminated	Disconnect all clients due to call terminated (channel deleted, voice server changed, etc.). Should not reconnect.

HTTP

Our API will return semantically valid HTTP response codes based on the success of your request. The following table can be used as a reference for response codes it will return.

HTTP Response Codes

Code	Meaning
200 (OK)	The request completed successfully.
201 (CREATED)	The entity was created successfully.
204 (NO CONTENT)	The request completed successfully but returned no content.
304 (NOT MODIFIED)	The entity was not modified (no action was taken).
400 (BAD REQUEST)	The request was improperly formatted, or the server couldn’t understand it.
401 (UNAUTHORIZED)	The Authorization header was missing or invalid.
403 (FORBIDDEN)	The Authorization token you passed did not have permission to the resource.
404 (NOT FOUND)	The resource at the location specified doesn’t exist.
405 (METHOD NOT ALLOWED)	The HTTP method used is not valid for the location specified.
429 (TOO MANY REQUESTS)	You are being rate limited, see Rate Limits.
502 (GATEWAY UNAVAILABLE)	There was not a gateway available to process your request. Wait a bit and retry.
5xx (SERVER ERROR)	The server had an error processing your request (these are rare).

JSON

Along with the HTTP error code, our API can also return more detailed error codes through a code key in the JSON error response. The response will also contain a message key containing a more friendly error string. Some of these errors may include additional details in the form of Error Messages provided by an errors object.

JSON Error Codes

Code	Meaning
0	General error (such as a malformed request body, amongst other things)
10001	Unknown account
10002	Unknown application
10003	Unknown channel
10004	Unknown guild
10005	Unknown integration
10006	Unknown invite
10007	Unknown member
10008	Unknown message
10009	Unknown permission overwrite
10010	Unknown provider
10011	Unknown role
10012	Unknown token
10013	Unknown user
10014	Unknown emoji
10015	Unknown webhook
10016	Unknown webhook service
10020	Unknown session
10021	Unknown Asset
10026	Unknown ban
10027	Unknown SKU
10028	Unknown Store Listing
10029	Unknown entitlement
10030	Unknown build
10031	Unknown lobby
10032	Unknown branch
10033	Unknown store directory layout
10036	Unknown redistributable
10038	Unknown gift code
10049	Unknown stream
10050	Unknown premium server subscribe cooldown
10057	Unknown guild template
10059	Unknown discoverable server category
10060	Unknown sticker
10061	Unknown sticker pack
10062	Unknown interaction
10063	Unknown application command
10065	Unknown voice state
10066	Unknown application command permissions
10067	Unknown Stage Instance
10068	Unknown Guild Member Verification Form
10069	Unknown Guild Welcome Screen
10070	Unknown Guild Scheduled Event
10071	Unknown Guild Scheduled Event User
10087	Unknown Tag
10097	Unknown sound
10124	Unknown invite target users job (invite exists but has no target users)
10129	Unknown invite target users (invite exists but has no target users)
20001	Bots cannot use this endpoint
20002	Only bots can use this endpoint
20009	Explicit content cannot be sent to the desired recipient(s)
20012	You are not authorized to perform this action on this application
20015	This action requires a premium subscription
20016	This action cannot be performed due to slowmode rate limit
20018	Only the owner of this account can perform this action
20022	This message cannot be edited due to announcement rate limits
20024	Under minimum age
20028	The write action you are performing on the channel has hit the write rate limit
20029	The write action you are performing on the server has hit the write rate limit
20031	Your Stage topic, server name, server description, or channel names contain words that are not allowed
20035	Guild premium subscription level too low
30001	Maximum number of guilds reached (100)
30002	Maximum number of friends reached (1000)
30003	Maximum number of pins reached for the channel (250)
30004	Maximum number of recipients reached (10)
30005	Maximum number of guild roles reached (250)
30007	Maximum number of webhooks reached (15)
30008	Maximum number of emojis reached
30010	Maximum number of reactions reached (20)
30011	Maximum number of group DMs reached (10)
30013	Maximum number of guild channels reached (500)
30015	Maximum number of attachments in a message reached (10)
30016	Maximum number of invites reached (1000)
30018	Maximum number of animated emojis reached
30019	Maximum number of server members reached
30030	Maximum number of server categories has been reached (5)
30031	Guild already has a template
30032	Maximum number of application commands reached
30033	Maximum number of thread participants has been reached (1000)
30034	Maximum number of daily application command creates has been reached (200)
30035	Maximum number of bans for non-guild members have been exceeded
30037	Maximum number of bans fetches has been reached
30038	Maximum number of uncompleted guild scheduled events reached (100)
30039	Maximum number of stickers reached
30040	Maximum number of prune requests has been reached. Try again later
30042	Maximum number of guild widget settings updates has been reached. Try again later
30045	Maximum number of soundboard sounds reached
30046	Maximum number of edits to messages older than 1 hour reached. Try again later
30047	Maximum number of pinned threads in a forum channel has been reached
30048	Maximum number of tags in a forum channel has been reached
30052	Bitrate is too high for channel of this type
30056	Maximum number of premium emojis reached (25)
30058	Maximum number of webhooks per guild reached (1000)
30060	Maximum number of channel permission overwrites reached (1000)
30061	The channels for this guild are too large
40001	Unauthorized. Provide a valid token and try again
40002	You need to verify your account in order to perform this action
40003	You are opening direct messages too fast
40004	Send messages has been temporarily disabled
40005	Request entity too large. Try sending something smaller in size
40006	This feature has been temporarily disabled server-side
40007	The user is banned from this guild
40012	Connection has been revoked
40018	Only consumable SKUs can be consumed
40019	You can only delete sandbox entitlements.
40032	Target user is not connected to voice
40033	This message has already been crossposted
40041	An application command with that name already exists
40043	Application interaction failed to send
40058	Cannot send a message in a forum channel
40060	Interaction has already been acknowledged
40061	Tag names must be unique
40062	Service resource is being rate limited
40066	There are no tags available that can be set by non-moderators
40067	A tag is required to create a forum post in this channel
40074	An entitlement has already been granted for this resource
40094	This interaction has hit the maximum number of follow up messages
40333	Cloudflare is blocking your request. This can often be resolved by setting a proper User Agent
50001	Missing access
50002	Invalid account type
50003	Cannot execute action on a DM channel
50004	Guild widget disabled
50005	Cannot edit a message authored by another user
50006	Cannot send an empty message
50007	Cannot send messages to this user
50008	Cannot send messages in a non-text channel
50009	Channel verification level is too high for you to gain access
50010	OAuth2 application does not have a bot
50011	OAuth2 application limit reached
50012	Invalid OAuth2 state
50013	You lack permissions to perform that action
50014	Invalid authentication token provided
50015	Note was too long
50016	Provided too few or too many messages to delete. Must provide at least 2 and fewer than 100 messages to delete
50017	Invalid MFA Level
50019	A message can only be pinned to the channel it was sent in
50020	Invite code was either invalid or taken
50021	Cannot execute action on a system message
50024	Cannot execute action on this channel type
50025	Invalid OAuth2 access token provided
50026	Missing required OAuth2 scope
50027	Invalid webhook token provided
50028	Invalid role
50033	Invalid Recipient(s)
50034	A message provided was too old to bulk delete
50035	Invalid form body (returned for both application/json and multipart/form-data bodies), or invalid Content-Type provided
50036	An invite was accepted to a guild the application’s bot is not in
50039	Invalid Activity Action
50041	Invalid API version provided
50045	File uploaded exceeds the maximum size
50046	Invalid file uploaded
50054	Cannot self-redeem this gift
50055	Invalid Guild
50057	Invalid SKU
50067	Invalid request origin
50068	Invalid message type
50070	Payment source required to redeem gift
50073	Cannot modify a system webhook
50074	Cannot delete a channel required for Community guilds
50080	Cannot edit stickers within a message
50081	Invalid sticker sent
50083	Tried to perform an operation on an archived thread, such as editing a message or adding a user to the thread
50084	Invalid thread notification settings
50085	before value is earlier than the thread creation date
50086	Community server channels must be text channels
50091	The entity type of the event is different from the entity you are trying to start the event for
50095	This server is not available in your location
50097	This server needs monetization enabled in order to perform this action
50101	This server needs more boosts to perform this action
50109	The request body contains invalid JSON.
50110	The provided file is invalid.
50123	The provided file type is invalid.
50124	The provided file duration exceeds maximum of 5.2 seconds.
50131	Owner cannot be pending member
50132	Ownership cannot be transferred to a bot user
50138	Failed to resize asset below the maximum size: 262144
50144	Cannot mix subscription and non subscription roles for an emoji
50145	Cannot convert between premium emoji and normal emoji
50146	Uploaded file not found.
50151	The specified emoji is invalid
50159	Voice messages do not support additional content.
50160	Voice messages must have a single audio attachment.
50161	Voice messages must have supporting metadata.
50162	Voice messages cannot be edited.
50163	Cannot delete guild subscription integration
50167	Cannot send voice effect when user is server muted, deafened, or suppressed
50173	You cannot send voice messages in this channel.
50178	The user account must first be verified
50192	The provided file does not have a valid duration.
50278	Cannot send messages to this user due to having no mutual guilds
50600	You do not have permission to send this sticker.
60003	Two factor is required for this operation
80004	No users with DiscordTag exist
90001	Reaction was blocked
90002	User cannot use burst reactions
110000	Index not yet available. Try again later
110001	Application not yet available. Try again later
130000	API resource is currently overloaded. Try again a little later
150006	The Stage is already open
160002	Cannot reply without permission to read message history
160004	A thread has already been created for this message
160005	Thread is locked
160006	Maximum number of active threads reached
160007	Maximum number of active announcement threads reached
160014	You cannot forward a message whose content you cannot read
170001	Invalid JSON for uploaded Lottie file
170002	Uploaded Lotties cannot contain rasterized images such as PNG or JPEG
170003	Sticker maximum framerate exceeded
170004	Sticker frame count exceeds maximum of 1000 frames
170005	Lottie animation maximum dimensions exceeded
170006	Sticker frame rate is either too small or too large
170007	Sticker animation duration exceeds maximum of 5 seconds
180000	Cannot update a finished event
180002	Failed to create stage needed for stage event
200000	Message was blocked by automatic moderation
200001	Title was blocked by automatic moderation
220001	Webhooks posted to forum channels must have a thread_name or thread_id
220002	Webhooks posted to forum channels cannot have both a thread_name and thread_id
220003	Webhooks can only create threads in forum channels
220004	Webhook services cannot be used in forum channels
240000	Message blocked by harmful links filter
340015	Access to joining new servers has been limited for the user
350000	Cannot enable onboarding, requirements are not met
350001	Cannot update onboarding while below requirements
400001	Access to file uploads has been limited for this guild
500000	Failed to ban users
520000	Poll voting blocked
520001	Poll expired
520002	Invalid channel type for poll creation
520003	Cannot edit a poll message
520004	Cannot use an emoji included with the poll
520006	Cannot expire a non-poll message
530000	Your Discord application has not been granted the permission to use provisional accounts.
530001	The ID token JWT you have provided is expired. You will need to get another one issued from the identity provider.
530002	The issuer in the ID token JWT you have provided does not match what you have configured.
530003	The audience in the ID token JWT you have provided does not match the audience you specified in your OIDC configuration. Either update your configuration or pass in an ID token that was issued to your application.
530004	The ID token you provided was issued too long ago. Discord will not accept ID tokens issued beyond a week ago. You will need to get a new ID token issued from the identity provider.
530006	Discord failed to generate a unique username within the allotted time. This is not a terminal error, and should resolve itself upon a retry.
530007	Your client secret is invalid. Double check what you are sending or regenerate your client secret.

Example JSON Error Response

{
  "message": "Invalid authentication token",
  "code": 50014
}

RPC

RPC is the local Discord server running on localhost. Access to the RPC server requires approval from Discord.

RPC Error Codes

Code	Name	Description
1000	Unknown error	An unknown error occurred.
4000	Invalid payload	You sent an invalid payload.
4002	Invalid command	Invalid command name specified.
4003	Invalid guild	Invalid guild ID specified.
4004	Invalid event	Invalid event name specified.
4005	Invalid channel	Invalid channel ID specified.
4006	Invalid permissions	You lack permissions to access the given resource.
4007	Invalid client ID	An invalid OAuth2 application ID was used to authorize or authenticate with.
4008	Invalid origin	An invalid OAuth2 application origin was used to authorize or authenticate with.
4009	Invalid token	An invalid OAuth2 token was used to authorize or authenticate with.
4010	Invalid user	The specified user ID was invalid.
5000	OAuth2 error	A standard OAuth2 error occurred; check the data object for the OAuth2 error details.
5001	Select channel timed out	An asynchronous SELECT_TEXT_CHANNEL/SELECT_VOICE_CHANNEL command timed out.
5002	GET_GUILD timed out	An asynchronous GET_GUILD command timed out.
5003	Select voice force required	You tried to join a user to a voice channel but the user was already in one.
5004	Capture shortcut already listening	You tried to capture more than one shortcut key at once.

RPC Close Event Codes

Code	Name	Description
4000	Invalid client ID	You connected to the RPC server with an invalid client ID.
4001	Invalid origin	You connected to the RPC server with an invalid origin.
4002	Rate limited	You are being rate limited.
4003	Token revoked	The OAuth2 token associated with a connection was revoked, get a new one!
4004	Invalid version	The RPC Server version specified in the connection string was not valid.
4005	Invalid encoding	The encoding specified in the connection string was not valid.