Suno API 报错：401、403、429 全清单
调用 Suno API 常见的报错与排查顺序：鉴权失败、余额不足、限流、forbidden、任务卡在生成中、任务失败、音频拿不到。按现象分组，每条给出先看什么、怎么恢复。
接口报错最浪费时间的地方，不是错误本身，而是在错误的那一层找原因。先按下表定位层次，再进对应小节。
第一步：判断错在哪一层
| 现象 | 大概率在哪一层 | 先看什么 |
|---|---|---|
| HTTP 401 | 鉴权 | 请求头里的密钥是否正确、是否带了多余空格或换行 |
| HTTP 403 | 账户 | 余额是否够、密钥是否有该接口权限 |
| HTTP 429 | 频率 | 是不是在紧密轮询，改成按秒退避 |
| 任务一直不动 | 任务 | 状态字段是 pending 还是 processing，别用音频字段判断 |
| 任务失败 | 上游 | 失败原因文本，以及有没有自动退费 |
| 音频打不开 | 交付 | 拿的是不是当前返回的地址 |
401：密钥没被认出来
三种最常见的原因，按概率排：
- 请求头写成了
Authorization: YOUR_KEY，漏了Bearer前缀。 - 复制密钥时把末尾的换行或空格一起复制进去了，肉眼看不出来。
- 密钥已经被删除或轮换了，但本地配置还是旧的。
排查方式很简单：用同一把密钥发一个最小的查询请求。查询能通、生成报 401，说明不是密钥问题；两个都 401，就是密钥本身。
403：密钥有效，但这次调用不被允许
绝大多数是余额不足。先看账户余额，再确认这次调用是否需要额外权限。充值后重发同一个请求即可，不需要改参数。
429：被限流了
429 通常不是错误，而是你的调用节奏太快。最常见的触发方式是在生成后用死循环不停查询状态。
正确做法：查询间隔放到 10 到 15 秒，遇到 429 按指数退避重试（1 秒、2 秒、4 秒、8 秒）。一次生成通常几十秒到几分钟完成，把间隔拉开既不影响体验，也不触发限流。
forbidden：音频地址打不开
如果你拿到的是上游地址，打开时看到 AccessDenied 或 forbidden，说明那是一个受限地址，不是给你的最终交付地址。这类地址只在特定会话或特定时间内有效，过期或换环境就会被拒。
处理办法：不要保存和使用历史地址，也不要自己拼接地址；每次都用接口当前返回的那个地址。本站的音频走自己的 CDN 域名，返回的是可直接访问的地址，不依赖上游会话。
任务层面：卡住、失败、退费
状态字段会依次经过 pending、submitted、processing，最后到 completed。两个常见误判：
- 用音频字段判断是否完成。生成过程中音频字段本来就是空的，应该看状态字段。
- 把“生成中”当成失败。一首歌几十秒到几分钟很正常，先等满再判断。
真失败时，任务会带失败原因，并且自动退费——不需要提交工单。如果余额没回来，先确认任务状态确实是失败而不是仍在处理。
排查清单
- 先确认 HTTP 状态码，再决定看哪一层。
- 鉴权问题用最小请求单独验证密钥。
- 轮询间隔 10 到 15 秒，429 用指数退避。
- 只用接口当前返回的音频地址，不缓存、不拼地址。
- 判断任务结果看状态字段，不看有没有音频地址。
- 失败先看原因文本，退费是自动的。