Errors and troubleshooting
Get a bot online, diagnose permissions and recover without repeating unsafe actions.
Examples use the bot client from Your first bot.
Understand API errors
Both SDKs expose RiscordError.status. HTTP helpers retry supported reads, replacements and keyed sends with bounded attempts. Unkeyed moderation actions are not automatically repeated.
| Status | Next step |
|---|---|
| 400 | Check the field names, types, command schema and payload limits |
| 401 | Check RISCORD_BOT_TOKEN and reset a leaked or invalid token |
| 403 | Check install consent, selected channels, hierarchy and recipient privacy |
| 404 | Check the resource ID and whether the bot can still access it |
| 409 | Refresh replaced state or explicitly rejoin an ended voice connection |
| 429 | Honor Retry-After and reduce request volume |
| 503 | Temporary capacity limit; honor Retry-After and use bounded retries |
My command is missing
- Confirm the bot process is running and the gateway reached ready.
- Register the command and include its intended server or dm context.
- Check that the bot is installed in this server and can view the channel.
- If you changed requested permissions, reauthorize the installation.
My embed is hidden or rejected
- Use SDK 0.3.0 or newer and pass embeds as a list, even for one card.
- In a server channel, check Embed Links in the application, installation and channel permissions. Suppressed embeds remain stored.
- Check the per-field and combined text limits, HTTP(S) artwork URLs and RGB color value.
- Resolve relative upload paths to absolute HTTP(S) URLs for embed artwork. imageUrl and fileUrl message fields can use relative upload paths.
- When editing, use an empty list to clear embeds. Null / None is not an embed list.
A reply edit no longer works
Reply handles last fifteen minutes. Their bot installation, original requester’s access and private/public audience are checked again for every edit or deletion. A deleted reply cannot be edited. Use the response ID returned by the message reply, rather than its interaction ID.
A click creates a fresh component interaction. editReply refers to the first response sent by that new interaction, rather than the older message containing the button. Use the channel/DM message helper to edit the bot’s own ordinary source message.
Voice joined, but there is no audio
- Check Connect and Speak in application requests, installation grants and the target channel.
- Check server mute and server deafen for the bot.
- Run ffmpeg -version on the bot host and confirm libopus and SRTP support.
- Use a local file or direct media URL, and check outbound UDP connectivity. There is no TCP media fallback.
- In JavaScript, join from ready. After a lost gateway, explicitly rejoin instead of reusing a closed VoiceConnection.
Share useful diagnostics
The Developer Portal shows bounded delivery and error codes. Include SDK version, runtime version, the operation and HTTP status in a bug report. Keep tokens, message content, form answers, private URLs and media encryption keys out of logs.
If an event triggers an external side effect, persist its operation ID. The SDK’s memory-only deduplication does not survive your process restarting.