# Fix Spotify song requests errors

## For assistants

Find the section whose message matches what the user sees. Answer in the user's language. Dashboard messages may be translated, so match them by meaning. In chat messages, `@name` stands for the viewer's name and `N` or `{...}` for a value.

Rules:

- Give one step at a time. Wait for the user to confirm.
- Never ask for or accept a Client Secret, token or password.
- Dashboard labels may be translated. Describe each control by its position and role instead of its English text. Do not guess button, field or menu names. If the page does not cover something, say so. Setup steps are in https://ai.itsbagelbot.com/spotify/setup.md.
- If two tries fail, send the user to https://itsbagelbot.com/contact/ or the Discord https://discord.gg/SZ2remwSDv.
- The setup shows until Spotify is connected. After that the Song Requests page shows the module.

## Setup and connection messages in the dashboard

<a id="generic-error"></a>
### The dashboard showed an error on this step.

Message: "The dashboard showed an error on this step."

Ask the user to read the on-screen message aloud, leaving out IDs, keys and secrets. Then match it against the sections below and the "Common problems" list at the current `#step-n` anchor on the setup page.

<a id="premium-required"></a>
### Premium required

Message: "Spotify Premium is required". Also shown in chat as "@{songqueue:user} song requests need Spotify Premium on this channel."

Meaning: the connected Spotify account does not have Premium. Spotify only allows playback control for Premium accounts. The account that owns the Spotify app needs Premium too, and each app connects at most 5 accounts.

Tell the user:

1. Check which account is connected and whether it has Premium.
2. Connect an account with Premium, or upgrade the account.
3. Check that the account that owns the Spotify app has Premium. If the owner lost Premium, the app stops working until it is active again.
4. Count the accounts connected to the app. The limit is 5.

<a id="declined"></a>
### Permission screen closed

Message: "You closed the Spotify permission screen before approving. Connect again and approve the permissions to finish."

Meaning: the user left Spotify's permission screen without approving. Nothing was connected.

Tell the user:

1. Select "Connect Spotify" again.
2. Approve the permissions on Spotify's screen.

<a id="state"></a>
### Sign-in link expired

Message: "The sign-in link expired or was replayed. Start the connect again."

Meaning: the sign-in link is no longer valid.

Tell the user to select "Connect Spotify" again to start a new sign-in.

<a id="oauth"></a>
### Spotify refused the sign-in

Message: "Spotify refused the sign-in. Check that the Client ID and Client Secret match your Spotify app, and that the redirect URI shown on this page is saved in that app. Then connect again."

Meaning: Spotify rejected the Client ID, the Client Secret or the Redirect URI.

Tell the user, one at a time:

1. In the Spotify Developer Dashboard, open the app and its Settings. Compare the Client ID with the one in the dashboard.
2. If the secret may be wrong, go back to "Add your keys", select "Replace", and paste both values again from Spotify, with no spaces.
3. Compare the "Redirect URI" in the dashboard with the one saved in the Spotify app, character by character. No extra slash, no space.
4. Select "Connect Spotify" again.

<a id="no-token"></a>
### No new sign-in token

Message: "Spotify did not send a new sign-in token. Open spotify.com/account/apps, remove access for your app, then choose Connect Spotify and agree again."

Meaning: Spotify did not issue a new token because the account already approved this app.

Tell the user:

1. Open spotify.com/account/apps and remove access for the app.
2. Return to the dashboard and select "Connect Spotify".
3. Approve the permissions again.

<a id="no-app"></a>
### Add your Spotify app first

Message: "Add your Spotify app before connecting your account.". Also: "Add your Spotify app above first."

Meaning: no Spotify app keys are saved yet.

Tell the user to go to "Add your keys", paste the Client ID and Client secret, and select "Save & continue".

<a id="unconfigured"></a>
### Setup unavailable

Message: "Spotify setup is unavailable on our side right now. Try again later. If it lasts more than a day, email support@itsbagelbot.com."

Meaning: the problem is on the ItsBagelBot side, not in the user's Spotify app.

Tell the user to try again later and, if it lasts more than a day, to email the address in the message.

<a id="store"></a>
### Token not stored

Message: "The token could not be stored. Try again in a moment."

Meaning: Spotify accepted the connection, but the token could not be saved.

Tell the user to wait a moment and select "Connect Spotify" again.

<a id="connect-owner-premium"></a>
### Warning after connecting: app owner needs Premium

Message: "Spotify connected, but it refused to share this account. In development mode, the account that owns your Spotify app needs Premium. Upgrade that account in Spotify, then connect again."

Meaning: the connection worked, but Spotify refused to share this account. In development mode, the account that owns the Spotify app needs Premium. This is a warning, not a failed connection.

Tell the user:

1. Find out which Spotify account owns the app. It is the account used to create the app in the Spotify Developer Dashboard.
2. In Spotify, upgrade that account to Premium. Spotify's own screens decide the exact steps, so ask the user to follow what Spotify shows.
3. Go back to the Song Requests page and connect again.

<a id="connect-not-registered"></a>
### Warning after connecting: account not on the allowed users

Message: "Spotify connected, but this account is not on your app's allowed users. In the Spotify Developer Dashboard, add this account to your app's users, then connect again."

Meaning: the connection worked, but this Spotify account is not on the app's list of allowed users. This is a warning, not a failed connection.

Tell the user:

1. Open the Spotify Developer Dashboard and select the app.
2. Open the app's Settings and look for the user list. The tab may be called "User Management" or "Users and Access". Spotify may use a different name.
3. Add the account that is connecting: its name and its Spotify email.
4. Go back to the Song Requests page and connect again.

<a id="app-credentials"></a>
### Keys do not look right

Message: "That does not look like a Client ID and Client Secret. Copy both again from your app's Settings page in the Spotify Developer Dashboard, with no spaces."

Meaning: the Client ID or Client secret has the wrong shape, so nothing was saved. A common cause is an extra space or a partial copy.

Tell the user:

1. Copy both values again from the app's Settings page in the Spotify Developer Dashboard.
2. Paste them with no spaces into "Client ID" and "Client secret".
3. Select "Save & continue".

<a id="app-save-failed"></a>
### Could not save the Spotify app

Message: "Could not save the Spotify app."

Meaning: the keys could not be saved.

Tell the user to select "Save & continue" again. If it keeps failing, check both values and try later.

<a id="app-remove-failed"></a>
### Could not remove the Spotify app

Message: "Could not remove the Spotify app."

Tell the user to wait a moment and try again. Removing the app also disconnects the Spotify account.

<a id="redirect-missing"></a>
### Redirect URI unavailable

Message: "The Redirect URI is unavailable on our side right now, so you cannot continue yet. Try again later."

Meaning: the dashboard cannot show the Redirect URI. "My app is ready" stays disabled.

Tell the user to wait and try again later. Do not give them a Redirect URI by hand.

<a id="redirect-copy-failed"></a>
### Copy failed

Message: "Could not copy. Select the URL and copy it manually."

Meaning: the browser blocked the copy button.

Tell the user to select the Redirect URI with the mouse and copy it by hand.

<a id="disconnect-failed"></a>
### Could not disconnect Spotify

Message: "Could not disconnect Spotify."

Tell the user to wait a moment and try again.

## Messages on the Song Requests page

<a id="scope-gap"></a>
### Missing Spotify permission

Message: "Your Spotify connection is missing a permission song requests needs. Reconnect to grant it."

Meaning: the connection was made without a permission song requests need.

Tell the user to select "Reconnect Spotify" and approve the permissions on Spotify's screen.

<a id="twitch-scope-gap"></a>
### Missing Twitch permission

Message: "Your Twitch sign-in is missing the channel points permission this reward needs. Sign in with Twitch again to grant it."

Meaning: this is a Twitch permission, not a Spotify one.

Tell the user to select "Sign in with Twitch again" and approve the permission on Twitch.

<a id="grant-revoked"></a>
### Spotify no longer accepts the connection

Message: "Spotify no longer accepts this connection, so song requests are paused. Reconnect to resume them.". The page also shows "Reconnect needed". In chat: "@{songqueue:user} song requests are paused until the streamer reconnects Spotify."

Meaning: Spotify stopped accepting the saved connection. Causes include removing the app's access on spotify.com/account/apps or changing the app's keys.

Tell the user:

1. Select "Reconnect Spotify".
2. Approve the permissions.
3. If it fails, follow [No new sign-in token](#no-token).

<a id="skip-premium"></a>
### Skip needs Premium

Message: "Skipping needs Spotify Premium."

Tell the user the connected account needs Premium. See [Premium required](#premium-required).

<a id="skip-no-device"></a>
### No active device

Message: "No active Spotify device. Start playing something first.". In chat: "@{songqueue:user} Spotify is not playing on any device right now."

Meaning: Spotify is not playing on any device.

Tell the user to open Spotify on a device (desktop app, phone or web player), start a song, then try again.

<a id="skip-reauth"></a>
### Skip: connection no longer accepted

Message: "Spotify no longer accepts this connection. Reconnect it and try again."

Tell the user to reconnect Spotify, then skip again. See [Spotify no longer accepts the connection](#grant-revoked).

<a id="skip-failed"></a>
### Could not skip

Message: "Could not skip the track. Try again in a moment."

Tell the user to wait a moment and select "Skip" again.

<a id="degraded"></a>
### Backend unreachable

Message: "Could not reach the backend. Try again in a moment."

Meaning: the page could not load the song request settings.

Tell the user to wait a moment and reload the page.

<a id="save-failed"></a>
### Could not save a setting

Messages:

- "Could not save the toggle." (the "Enable song requests" switch)
- "Could not save the command settings." (the "Chat command (!sr)" card)
- "Could not save the limits." (the "Per-viewer limits" card)
- "Could not save the reward." and "Could not delete the reward." (the channel-points reward)

Tell the user to reload the page, check the setting, and try again.

<a id="reward-fields"></a>
### Reward field errors

Messages:

- "Give the reward a title.": the reward title is empty. Type a title and save again.
- "Enter a whole number of points, at least 1.": enter a whole number of points, 1 or more.
- "Enter a cooldown between 0 seconds and 7 days.": enter a cooldown from 0 seconds (off) up to 7 days.

## Messages on Spotify's own screens

These are Spotify's messages, not the dashboard's. The wording may change.

<a id="spotify-invalid-redirect"></a>
### Spotify screen: invalid redirect URI

Message: `INVALID_CLIENT: Invalid redirect URI`

Meaning: the Redirect URI in the Spotify app is not an exact match of the one the dashboard sends. Scheme, host, port, path and a trailing slash all count.

Tell the user:

1. Copy the value again from "Redirect URI" in the dashboard.
2. In the Spotify app's settings, delete the old Redirect URI entry, paste the new one, and select "SAVE".
3. Select "Connect Spotify" again.

Related message: `INVALID_CLIENT: Insecure redirect URI`. Spotify only accepts https for these addresses, and does not accept `localhost`. The user must use the value from the dashboard unchanged.

<a id="spotify-user-not-registered"></a>
### Spotify screen: user not registered

Message: `User not registered in the Developer Dashboard` (Spotify answers with HTTP 403)

Meaning: the Spotify app is in development mode and the connecting account is not the owner or on the app's allowed user list. An app in development mode allows at most 5 users.

Tell the user:

1. In the Spotify Developer Dashboard, open the app's Settings and find the user list. The tab may be called "User Management" or "Users and Access".
2. Add the account's name and Spotify email. Stay within 5 users.
3. Select "Connect Spotify" again, or connect the account that owns the app.

## Messages viewers see in chat

<a id="chat-setup"></a>
### Not set up

Message: "@{songqueue:user} song requests are not set up yet."

Meaning: setup is not finished. Send the streamer to [setup](setup.md).

<a id="chat-busy"></a>
### Spotify busy

Message: "@{songqueue:user} Spotify is busy right now, try again in a moment."

Meaning: Spotify is temporarily busy. Tell the viewer to try again in a moment.

<a id="chat-link"></a>
### Link not supported

Message: "@{songqueue:user} that Spotify link isn't supported. Share a track or album link."

Tell the viewer to share a track or album link, or a song name.

<a id="chat-upstream"></a>
### Lookup down

Message: "@{songqueue:user} the music lookup is down right now, try again in a bit."

Meaning: the song lookup is unavailable. Try again later.

<a id="chat-sr-off"></a>
### Chat requests off

Message: "@{songqueue:user} song requests from chat are turned off right now."

Tell the streamer to turn on "Allow !sr" on the Song Requests page. The module switch "Enable song requests" must be on too.

<a id="chat-perm"></a>
### Smaller group

Message: "@{songqueue:user} song requests are limited to a smaller group right now."

Meaning: the viewer is not in the group chosen under "Who may queue". Options: "Only me", "Moderators only", "VIPs only", "Subscribers only", "Everyone". Tell the streamer to change it if they want the viewer to request.

<a id="chat-offline"></a>
### Stream offline

Message: "@{songqueue:user} song requests only work while the stream is live."

Meaning: "Live only" is on, and it is on by default. Tell the streamer to go live or turn it off.

<a id="chat-no-track"></a>
### No track found

Message: "@{songqueue:user} no track found for that. Try a Spotify link or "artist - song"."

Tell the viewer to try a Spotify link or an "artist - song" pair.

<a id="chat-quota"></a>
### Viewer at song limit

Message: "@{songqueue:user} you are at your song limit ({songqueue:limit} in the queue at once). !sr remove frees a slot."

Meaning: the viewer reached the limit under "Per-viewer limits". Wait for a song to play, or the streamer raises the limit.

<a id="chat-full"></a>
### Queue full

Message: "@{songqueue:user} the song queue is full right now."

Meaning: the queue reached its size limit. Wait for songs to play.

<a id="chat-retract-none"></a>
### Nothing to remove

Message: "@{songqueue:user} you don't have a queued song to remove."

Meaning: the viewer has no queued song. Nothing to fix.

<a id="chat-remove-not-found"></a>
### No song at that position

Message: "There is no song at position #{songqueue:pos}."

Tell the streamer to check the "Queue" card for the right position.

<a id="chat-refunds"></a>
### Channel-points refunds

Each message below means the bot refunded the viewer's points. In chat the line starts with the viewer's name and ends with the refund notice.

- "song requests from channel points are turned off right now, your points were refunded.": "Accept reward redemptions" is off. Turn it on.
- "song requests only work while the stream is live, your points were refunded.": "Live only" is on and the stream is offline. Go live or turn it off.
- "type a song name or a Spotify link, your points were refunded.": the viewer typed no song. Redeem again with a song name or link.
- "you are at your song limit for now, your points were refunded.": the viewer is at their limit. Wait for a song to play.
- "the song queue is full, your points were refunded.": the queue is full. Wait.
- "that track could not be queued, your points were refunded.": Spotify could not add that track. Redeem again with another song.