# 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

```json
{ "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`:

```json
{
  "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

```json
{ "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.
