Opcodes and Status Codes
Gateway
All Gateway events in Discord are tagged with an opcode that denotes the payload type. Your connection to the Gateway may also sometimes close. When it does, you will receive a close code that tells you what happened.
Gateway Opcodes
| Code | Name | Action | Description |
|---|---|---|---|
| 0 | Dispatch | Receive | An event was dispatched. |
| 1 | Heartbeat | Send/Receive | Keep the WebSocket connection alive. |
| 2 | Identify | Send | Start a new session during the initial handshake. |
| 3 | Presence Update | Send | Update the client's presence. |
| 4 | Voice State Update | Send | Join/leave or move between voice channels and calls. |
| 5 | Voice Server Ping | Send | Ping the Discord voice servers. |
| 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 guild members. |
| 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 | Acknowledge a received heartbeat. |
| 13 | Call Connect | Send | Request a private channels's pre-existing call data. |
| 14 | Guild Subscriptions | Send | Update subscriptions for a guild. |
| 18 | Stream Create | Send | Create a stream for the client. |
| 19 | Stream Delete | Send | End a client stream. |
| 20 | Stream Watch | Send | Watch a user's stream. |
| 21 | Stream Ping | Send | Ping a stream's voice server. |
| 22 | Stream Set Paused | Send | Pause or resume a client stream. |
| 28 | Request Forum Unreads | Send | Request forum channel unread counts. |
| 29 | Remote Command | Send | Send a remote command to an embedded (Xbox, PlayStation) voice session. |
| 30 | Request Deleted Entity IDs | Send | Request deleted entity IDs not matching a given hash for a guild. |
| 31 | Request Soundboard Sounds | Send | Request soundboard sounds for guilds. |
| 34 | Request Last Messages | Send | Request last messages for a guild's channels. |
| 35 | Search Recent Members | Send | Request information about recently-joined guild members. |
| 36 | Request Channel Statuses | Send | Request voice channel statuses for a guild. |
| 37 | Guild Subscriptions Bulk | Send | Update subscriptions for multiple guilds. |
| 38 | Guild Channels Resync | Send | Resynchronize accessible guild channels. |
Gateway Close Event Codes
| Code | Description | Explanation |
|---|---|---|
| 4000 | Unknown error | We're not sure what went wrong. Try reconnecting? |
| 4001 | Unknown opcode | You sent an invalid Gateway opcode or an invalid payload for an opcode. Don't do that! |
| 4002 | Decode error | You sent an invalid payload. Don't do that! |
| 4003 | Not authenticated | You sent us a payload prior to identifying, or this session has been invalidated. |
| 4004 | Authentication failed | The account token sent with your identify payload is incorrect. |
| 4005 | Already authenticated | You sent more than one identify payload. Don't do that! |
| 4007 | Invalid seq | The sequence sent when resuming the session was invalid. Reconnect and start a new session. |
| 4008 | Rate limited | Woah nelly! You're sending payloads too quickly. Slow it down! You will be disconnected on receiving this. |
| 4009 | Session timed out | Your session timed out. Reconnect and start a new one. |
| 4010 | Invalid shard | You sent us an invalid shard when identifying. |
| 4011 | Sharding required | The session would have handled too many guilds - you are required to shard your connection in order to connect. |
| 4012 | Invalid API version | You sent an invalid version for the Gateway. |
| 4013 | Invalid intent(s) | You sent an invalid intent for a Gateway Intent. You may have incorrectly calculated the bitwise value. |
| 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. |
Voice
The Voice Gateway has its own set of opcodes and close codes.
Voice Opcodes
| Code | Name | Action | Description |
|---|---|---|---|
| 0 | Identify | Send | Start a new voice WebSocket connection. |
| 1 | Select Protocol | Send | Select the voice protocol. |
| 2 | Ready | Receive | Complete the WebSocket handshake. |
| 3 | Heartbeat | Send/Receive | Keep the WebSocket connection alive. |
| 4 | Session Description | Receive | Describe the session. |
| 5 | Speaking | Send/Receive | Indicate which users are speaking. |
| 6 | Heartbeat ACK | Receive | Acknowledge a received heartbeat. |
| 7 | Resume | Send | Resume a previous session that was disconnected. |
| 8 | Hello | Receive | Sent immediately after connecting, contains the heartbeat_interval to use. |
| 9 | Resumed | Receive | Response to acknowledging a successful resume. |
| 11 | Client Connect | Receive | Indicate that clients have connected to the voice channel. |
| 12 | Video | Send/Receive | Describe the video session. |
| 13 | Client Disconnect | Receive | Indicate that a client has disconnected from the voice channel. |
| 14 | Session Update | Send/Receive | Indicate an update in session description. |
| 15 | Media Sink Wants | Send/Receive | Indicate the media streams wanted for simulcasting. |
| 16 | Voice Backend Version | Send/Receive | Version information about the voice backend. |
| 18 | Client Flags | Receive | Indicate a client's flags. |
| 20 | Client Platform | Receive | Indicate the platform a client is connected on |
Voice Close Event Codes
| Code | Description | Explanation |
|---|---|---|
| 4001 | Unknown opcode | You sent an invalid opcode. |
| 4002 | Failed to decode payload | You sent a 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 | Channel was deleted, you were kicked, voice server changed, or the main Gateway session was dropped. Should not reconnect. |
| 4015 | Voice server crashed | The server crashed. Our bad! Try resuming. |
| 4016 | Unknown encryption mode | We didn't recognize your encryption. |
HTTP
The 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. |
| 202 (ACCEPTED) | The request was accepted but the resource is not ready. A retry_after key should be present in the body. |
| 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) | You do not have permission to perform the requested action. |
| 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. |
| 409 (CONFLICT) | The requested resource update could not be completed due to the current state of the target resource. |
| 410 (GONE) | The resource being accessed is no longer available. |
| 413 (PAYLOAD TOO LARGE) | The request entity was too large. |
| 415 (UNSUPPORTED MEDIA) | The requested content type is not supported (CDN only). |
| 429 (TOO MANY REQUESTS) | You are being rate limited, see Rate Limits. |
| 502 (GATEWAY UNAVAILABLE) | There was no gateway available to process your request. Wait a bit and retry. |
| 503 (SERVICE UNAVAILABLE) | The service required to process your request is unavailable. Wait a bit and retry. |
| 5xx (SERVER ERROR) 1 | The server had an error processing your request. |
1 502, 504, 507, 522, 523, 524 should be retried with a backoff. The number of failed requests can be specified with the X-Failed-Requests header. Whether you retry other 5xx errors is up to you.
JSON
Along with the HTTP error code, the 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
Example JSON Error Response