> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting: Slack connection and sync failures (SLACK_TOKEN_*)

> Runbook for the three Slack OAuth and token error codes — SLACK_TOKEN_REDEMPTION_REJECTED, SLACK_TOKEN_REDEMPTION_FAILED, and SLACK_TOKEN_DECRYPT_FAILED: which step of the connect flow each one fires at, the operator decision tree, and when to reconnect versus when to retry.

# Troubleshooting: Slack connection and sync failures

The Slack integration connects your workspace through OAuth, then reads
your channel list with the stored bot token every time a page shows the
channel selector. Failures split cleanly along that boundary: the install
callback can fail to redeem the one-time authorization code
(`SLACK_TOKEN_REDEMPTION_*`), and the day-to-day channel read can fail to
decrypt the stored bot token (`SLACK_TOKEN_DECRYPT_FAILED`). The fix
differs per family, so read the code off the error envelope before
picking one.

## The two steps that fail differently

1. **Install (OAuth).** Settings → Integrations → Slack issues
   `GET /api/v1/integrations/slack/oauth/start`, which redirects your
   browser to Slack's authorize page. After you approve, Slack redirects
   back to `GET /api/v1/integrations/slack/oauth/callback` with a
   one-time `code`, and Orbit exchanges that code for the bot token.
   The two redemption codes fire here.
2. **Day-to-day operation.** Once connected, every surface that shows
   the channel selector calls
   `GET /api/v1/integrations/slack/channels`, which decrypts the stored
   bot token and lists the channels the bot can target. The decrypt
   code fires here, after a successful install.

A redemption error during install says nothing about your stored
token, and a decrypt failure on the channel read says nothing about
Slack's OAuth endpoint. Route on the code before choosing a fix.

## The three codes

| Code | HTTP | Where it fires | Meaning | Fix |
| - | - | - | - | - |
| `SLACK_TOKEN_REDEMPTION_REJECTED` | 400 | Install callback | Slack rejected the code exchange: the one-time code was already redeemed, expired, or did not match the install request that minted it | Re-initiate the install from the integrations card; never replay an old callback URL |
| `SLACK_TOKEN_REDEMPTION_FAILED` | 502 | Install callback | Orbit could not reach Slack's token exchange endpoint, or the endpoint returned a server error | Transient. Wait \~30s and start the install again; if it persists, escalate with `meta.request_id` |
| `SLACK_TOKEN_DECRYPT_FAILED` | 502 | `GET /api/v1/integrations/slack/channels` | The stored bot token cannot be decrypted — almost always a credential written under a different environment or encryption key | Disconnect and re-connect the Slack integration; do not rotate keys |

The envelope on every one of the three carries the trace id support
needs:

```json theme={null}
{
  "error": {
    "code": "SLACK_TOKEN_REDEMPTION_REJECTED",
    "message": "Slack rejected token redemption: invalid_code",
    "status": 400
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-10-16T09:12:44Z"
  }
}
```

## Decision tree for operators

**Install page loops back without Connected.** The callback returned a
rejection instead of completing. Read the envelope:
`SLACK_TOKEN_REDEMPTION_REJECTED` means the code was stale or replayed;
a 401 `INVALID_STATE` means the signed state expired or was superseded
before the callback arrived. The recovery is the same either way:
close the tab and start the install fresh from Settings →
Integrations → Slack so a new state and code pair is minted. Do not
refresh the callback page, and do not retry the URL from browser
history — the code is one-time, and the replay is exactly what the
rejection records.

**Monitor page shows Disconnected shortly after Connected.** The
install saved a credential, but the first channel read could not use
it. That is the `SLACK_TOKEN_DECRYPT_FAILED` family: the stored
ciphertext is not recoverable, usually because the credential was
written under a different environment or encryption key (for example
after a restore into a fresh environment). Disconnect the Slack
integration and connect it again — the reconnect replaces the stored
credential with a freshly encrypted one. Rotating keys does not fix
it, and it would make every other stored credential unreadable too.

**Channel selector empty after reconnect.** Read the response (network
tab, or retry the `GET /api/v1/integrations/slack/channels` call) and
branch on it:

* `SLACK_TOKEN_DECRYPT_FAILED` — the reconnect did not land. Repeat the
  disconnect/connect cycle once and confirm the integrations card
  shows Connected before reopening the selector.
* A 200 with an empty `channels` array — the connection is healthy,
  but the bot is not a member of any channel yet. In Slack, invite the
  bot to the channels it should target, then reopen the selector.
  Archived channels are excluded by design.

## Common missteps

* **Re-clicking the Slack install button in a callback loop.** Every
  click mints a fresh signed state and supersedes the previous one, so
  the callback the first tab was about to deliver now references a
  superseded state and is rejected legitimately. Run one install pass
  at a time, start to finish.
* **Replaying a callback URL from history or a forwarded link.** The
  `code` on that URL is one-time and bound to the state that minted
  it; replaying it returns `SLACK_TOKEN_REDEMPTION_REJECTED`.
* **Pasting a bot token manually.** The integration is OAuth-only.
  There is no field that accepts a copied `xoxb-` token, and a
  manually copied token could never carry the storage envelope the
  read path expects. If a token was copied out of Slack, revoke it in
  Slack and run the OAuth install instead.
* **Rotating encryption keys to clear
  `SLACK_TOKEN_DECRYPT_FAILED`.** The unreadable credential has to be
  replaced, not re-keyed; the reconnect does that. A key rotation in
  response would leave the bad row in place and break every other
  stored integration credential.

## What support needs

If a clean reconnect still fails, open a ticket with:

* The `meta.request_id` from the failed callback — required for any
  5xx, useful for every code.
* The workspace ID Slack shows for the workspace (Slack → Settings →
  Workspace settings, the `T…` identifier).
* The timestamp of the attempt, plus the browser and OS you ran the
  install from.

## See also

* [Slack channel](/channels/slack) — what the integration does once
  connected, and the channel selector behaviour
* [Slack onboarding guide](/guides/slack-onboarding) — the full
  install ordering, scopes, and first-sync checks
* [Error Code Reference](/reference/error-codes) — every code in one
  table
* [Troubleshooting hub](/reference/troubleshooting-hub) — every
  runbook in one index


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.