使用 Spotify Web API 的 /me/player/queue 端点添加歌曲时返回 404 错误，通常并非 URI 格式或权限问题，而是因目标播放设备未处于“活跃播放状态”所致——该端点要求设备已启动播放（至少有一首歌正在播放或已加载），否则会静默返回 404。
使用 spotify web api 的 `/me/player/queue` 端点添加歌曲时返回 404 错误，通常并非 uri 格式或权限问题，而是因目标播放设备未处于“活跃播放状态”所致——该端点要求设备已启动播放（至少有一首歌正在播放或已加载），否则会静默返回 404。
在开发基于 Spotify Web API 的播放控制功能时，开发者常遇到 POST /v1/me/player/queue?uri=... 接口持续返回 404 Not Found 的问题，即使 URI 格式正确（如 spotify:track:3OF9rTCYjLEplmYMynYvHG）、访问令牌有效、且其他 API（如获取用户信息、播放状态）均正常工作。根本原因在于 Spotify 的队列添加机制存在一个关键前提条件：必须存在一个处于活跃状态（active）的播放设备，且该设备当前正在播放或已准备就绪（即已调用过 play 或已加载上下文）。
? 为什么会出现 404？——不是资源不存在，而是“设备不可达”
尽管错误提示为 Track not found in Spotify catalog，但实际并非曲目缺失（可通过 GET /v1/tracks/{id} 验证其存在），而是 Spotify 后端在处理 /queue 请求时，首先尝试将歌曲推送到当前活跃设备；若无活跃设备，API 会直接返回 404，而非更明确的 403 Forbidden 或 422 Unprocessable Entity。这是 Spotify 文档中未显式强调、但已被广泛验证的行为（官方文档仅说明：“The user must have a Spotify Premium account and an active device.”）。
✅ 正确实现步骤（含代码示例）
以下是一个健壮的队列添加流程，包含设备预检、播放初始化和批量入队：
// 1. 确保设备活跃：先获取可用设备列表，选择或激活一个设备
const getActiveDevice = async (token) => {
const res = await fetch('https://api.spotify.com/v1/me/player/devices', {
headers: { 'Authorization': `Bearer ${token}` }
});
const { devices } = await res.json();
const activeDevice = devices.find(d => d.is_active) || devices[0];
if (!activeDevice) {
throw new Error('No available Spotify devices found. Please open Spotify app or web player.');
}
return activeDevice.id;
};
// 2. （可选但推荐）确保设备已“就绪”：触发一次空播放或恢复播放
const ensurePlaybackReady = async (token, deviceId) => {
try {
// 尝试恢复播放（若已暂停）
await fetch(`https://api.spotify.com/v1/me/player/play?device_id=${deviceId}`, {
method: 'PUT',
headers: { 'Authorization': `Bearer ${token}` },
body: JSON.stringify({}) // 空 body 表示恢复当前上下文
});
} catch (err) {
// 若无当前上下文，需先提供基础播放项（例如：播放一个占位曲目）
const placeholderUri = 'spotify:track:4cOdK2wGLETKBW3PvgPWqT'; // e.g., "Spotify Intro"
await fetch(`https://api.spotify.com/v1/me/player/play?device_id=${deviceId}`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ uris: [placeholderUri] })
});
await new Promise(resolve => setTimeout(resolve, 800)); // 等待短暂缓冲
}
};
// 3. 批量添加至队列（URI 必须为标准格式：spotify:track:{id}）
const addToQueue = async (token, uris, max = 10) => {
const deviceId = await getActiveDevice(token);
await ensurePlaybackReady(token, deviceId);
for (const uri of uris.slice(0, max)) {
try {
const url = new URL('https://api.spotify.com/v1/me/player/queue');
url.searchParams.set('uri', uri);
url.searchParams.set('device_id', deviceId); // 显式指定设备 ID！
const res = await fetch(url.toString(), {
method: 'POST',
headers: { 'Authorization': `Bearer ${token}` }
});
if (res.ok) {
console.log(`✅ Added to queue: ${uri}`);
} else if (res.status === 404) {
console.warn(`⚠️ 404 — Device likely inactive or URI invalid: ${uri}`);
} else {
console.error(`❌ Queue add failed (${res.status}):`, await res.text());
}
} catch (err) {
console.error('Network or auth error:', err);
}
}
};
// 使用示例
const trackUris = [
'spotify:track:3OF9rTCYjLEplmYMynYvHG',
'spotify:track:2VZJ6sHkz0u7f5dFqyXG1a'
];
addToQueue(accessToken, trackUris);
⚠️ 关键注意事项
- device_id 参数不可或缺：即使有活跃设备，也强烈建议显式传入 device_id（通过 /devices 接口获取）。省略该参数时，API 会尝试使用“默认活跃设备”，但该逻辑不稳定，尤其在多设备环境下易失效。
- 播放状态是硬性依赖：/queue 不是独立操作，而是播放会话的延伸。从未播放过的设备、刚启动但未调用 play 的设备，均无法接受队列请求。
- 免费账户限制：Spotify Free 用户无法使用 /player/queue（即使设备活跃），该功能仅对 Premium 账户开放。务必在调用前校验用户订阅状态（GET /v1/me 中的 product 字段）。
- URI 格式严格：仅支持 spotify:track:{id} 格式，不支持专辑、播放列表或本地文件 URI；ID 必须为 22 位 Base62 字符串，可通过正则 /^spotify:track:[0-9a-zA-Z]{22}$/ 预校验。
- 跨页面状态丢失：如问题中所述，拆分 HTML 页面可能导致 access_token 或设备上下文重置。建议将播放控制逻辑封装为单页应用（SPA）或通过 localStorage + 定期 token 刷新机制维持会话连续性。
✅ 总结
解决 Spotify 队列 404 问题的核心思路是：将“添加队列”视为“播放会话的延续”，而非独立资源操作。务必完成三步闭环：① 发现并确认活跃设备；② 通过 play 确保设备进入就绪态；③ 显式携带 device_id 发起队列请求。跳过任一环节，都可能触发静默 404。这一行为虽属设计约束，但通过规范流程即可稳定规避。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
