Errors
Every error answers a JSON body with a numeric code and a message, in Discord's shapes; this page lists the shapes and every code the integration surface uses.
The error shape
{ "message": "Missing Access", "code": 50001 }
code is 0 where Discord uses no specific code (for example 401 and 404 on an unknown transcript). Branch on the HTTP status and code, not on message.
The form error shape
Validation failures answer 400 with code 50035, Invalid Form Body, and name the field at fault under errors:
{
"message": "Invalid Form Body",
"code": 50035,
"errors": {
"topic": {
"_errors": [
{ "code": "BASE_TYPE_INVALID", "message": "A description of the conversation is required" }
]
}
}
}
The key under errors is the field name. For a bad entry in the talkers array when opening a conversation it is talkers.<index>, for example talkers.0. Read the human-readable reason from errors.<field>._errors[].message.
Codes
| HTTP | Code | Message | When |
|---|---|---|---|
| 400 | 50035 | Invalid Form Body | A field failed validation. See the form error shape above and the field rules on each page. |
| 400 | 30013 | Maximum number of guild channels reached (<cap>) | Opening a conversation while channel_cap conversations are already open. Close one first, or ask platform staff to raise the cap. |
| 400 | 30001 | Maximum number of integrations reached | Creating a 26th integration from the portal. |
| 401 | 0 | 401: Unauthorized | No credential, or one that is invalid: a reset secret key, or a channel token that expired, was revoked, names a talker removed from the conversation, or belongs to a closed conversation. |
| 403 | 50001 | Missing Access | The credential is valid but may not use this route: a channel token on any route outside its own channel, the secret key on another integration or on a numeric integration id instead of @me, or a signed-in account without chat integration access. Also a signed-in account that is not a member of the server, opening a transcript page. |
| 403 | 50013 | Missing Permissions | A talker trying to attach files or to delete someone else's message. |
| 403 | 50013 | Cannot edit a message authored by another user | A talker editing someone else's message. |
| 403 | 50013 | This server is reserved for a chat integration; conversations are opened by the integration | Anyone other than the integration's bot creating a channel in the reserved server, or anyone creating a thread there. |
| 403 | 50013 | This channel is reserved for the chat integration and cannot be deleted | Deleting internal or logging. |
| 404 | 10002 | Unknown Application | The integration id does not exist or is not a chat integration, or @me was used without the secret key. |
| 404 | 10003 | Unknown Channel | The channel_id on an integration route is not an open conversation of this integration (it never existed, it closed, or it is internal or logging). |
| 404 | 10013 | Unknown User | No talker with that external_id exists in this integration. |
| 404 | 0 | Unknown Transcript | The transcript does not exist, belongs to another integration, or the signature on a transcript link is wrong. |
| 429 | 0 | You are being rate limited. | A channel token went over a route's rate limit. Wait retry_after seconds (a float) and retry. The secret key is never rate limited. |
Three refusals specific to the reserved server are form errors (code 50035) rather than codes of their own:
| Field | Message | When |
|---|---|---|
name | This channel is reserved for the chat integration and keeps its name | Renaming internal or logging. |
type | A chat integration server holds text channels only | Creating any channel other than a text channel in the reserved server. |
topic | A description of the conversation is required | Opening a conversation with no topic, through either route. |
The 429 body
{ "message": "You are being rate limited.", "retry_after": 0.734, "global": false, "code": 0 }
The Retry-After header carries the same wait rounded up to whole seconds, and the X-RateLimit-* headers describe the bucket as on Discord.