Shana API 接入排错指南：401、403、429、502/503 与路径检查

排错时每次只改变一个变量，并保留不含凭据的记录。先确认 Base URL 是 https://shana.baby/v1，客户端协议为 Responses。不要把网页首页地址当接口地址，也不要在浏览器中存储、读取或代发 API Key。

401：认证未通过

检查本地受控配置是否被当前客户端读取，Key 是否为空、含多余空格或使用了错误配置档。401 不应靠重试解决；不要把 Key 粘贴到网页控制台、工单、截图或聊天中。

403：身份已识别但无权限

403 通常应检查账号、访问范围或服务端策略是否允许该请求。保留时间、客户端版本和已脱敏错误文本，然后按服务端说明核对；同样不应重复请求或更换浏览器脚本。

429：频率限制

停止紧密循环。只对可重试请求做有界重试：最多 3 次，间隔可为 2 秒、4 秒、8 秒；仍失败就停止并记录错误。不要把每次重试都并发放大。

502/503：临时服务错误

502/503 可能是短暂的上游或服务状态问题。采用同样最多 3 次的 2 秒、4 秒、8 秒有界重试；若持续失败，保留脱敏证据并等待后续处理，而不是承诺固定恢复时间。

重复 /v1 与错误追加端点

当 Base URL 已经是 https://shana.baby/v1 时，不要再手工拼出重复的 /v1。使用支持 Responses 的客户端时，也不要自行在 Base URL 后错误追加 /responses 或 /chat/completions；这些路径应由当前客户端与协议设置按其文档处理。

可复现操作案例

在无业务数据的短请求上，先核对 Base URL 与 Responses；再故意使用错误配置档观察 401 类错误，恢复后只对临时错误执行最多三次的有界重试。记录中只保留时间、状态码和已脱敏文本，不保留 Key、完整请求头或用户内容。

最小请求仍失败时，可查阅 Shana Codex 接入说明。