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

HTTPCodeMessageWhen
40050035Invalid Form BodyA field failed validation. See the form error shape above and the field rules on each page.
40030013Maximum 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.
40030001Maximum number of integrations reachedCreating a 26th integration from the portal.
4010401: UnauthorizedNo 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.
40350001Missing AccessThe 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.
40350013Missing PermissionsA talker trying to attach files or to delete someone else's message.
40350013Cannot edit a message authored by another userA talker editing someone else's message.
40350013This server is reserved for a chat integration; conversations are opened by the integrationAnyone other than the integration's bot creating a channel in the reserved server, or anyone creating a thread there.
40350013This channel is reserved for the chat integration and cannot be deletedDeleting internal or logging.
40410002Unknown ApplicationThe integration id does not exist or is not a chat integration, or @me was used without the secret key.
40410003Unknown ChannelThe 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).
40410013Unknown UserNo talker with that external_id exists in this integration.
4040Unknown TranscriptThe transcript does not exist, belongs to another integration, or the signature on a transcript link is wrong.
4290You 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:

FieldMessageWhen
nameThis channel is reserved for the chat integration and keeps its nameRenaming internal or logging.
typeA chat integration server holds text channels onlyCreating any channel other than a text channel in the reserved server.
topicA description of the conversation is requiredOpening 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.