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

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.
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:

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

Reference

Troubleshooting: Slack connection and sync failures (SLACK_TOKEN_*)

Troubleshooting: Slack connection and sync failures

The two steps that fail differently

The three codes

Decision tree for operators

Common missteps

What support needs

See also

​Troubleshooting: Slack connection and sync failures

​The two steps that fail differently

​The three codes

​Decision tree for operators

​Common missteps

​What support needs

​See also

Troubleshooting: Slack connection and sync failures

The two steps that fail differently

The three codes

Decision tree for operators

Common missteps

What support needs

See also