有道翻译API如何设置请求频率上限避免超限报错？
在有道翻译API控制台为应用设定QPS上限，配合令牌桶与退避重试，可稳控调用量，避免超限报错。
功能定位：为什么必须手动设限
有道翻译API对未设置频率上限的应用默认采用「账户���总QPS」兜底，当同一账户下多个业务并行抢量时，极易触发429 Too Many Requests。手动给每个应用分配独立上限，能把「全局抢量」转化为「局部可控」，提前在控制台层面把风险隔离掉。
控制台最短路径：30 秒完成配置
网页端（PC/Mac）
- 登录ai.youdao.com → 右上角「控制台」→ 左侧「我的应用」。
- 点击目标应用卡片右侧「配置」→ 进入「流量控制」标签。
- 在「QPS 上限」输入框内填写预期值（整数，最小 1），点「保存」。
- 页面顶部出现「已生效」绿条即代表云端完成分发，无需重启服务。
移动端（Android/iOS）
截至当前的最新版本，移动端控制台仅提供只读视图。若需修改，请使用系统浏览器访问桌面版网页，或在「分享」菜单里选择「请求桌面网站」后按上述步骤操作。
提示：修改后 1–2 分钟内会同步到边缘节点，若业务处于长连接状态，建议主动重连一次以立即拿到新配额。
选多少 QPS 才安全？先算「峰值×冗余」
经验性观察：把过去 7 天的调用峰值分钟数除以 60 得到「秒级峰值」，再乘以 1.5 倍冗余，即可作为初始上限。举例：峰值分钟 6000 次 → 秒级 100 次 → 设 150 次。后续每周回看一次「429 占比」曲线，若持续为 0，可再下调 10% 节省预算。
代码层兜底：令牌桶 + 退避重试
控制台只解决「云端挡刀」，客户端仍可能因网络抖动瞬时突刺。推荐在 SDK 侧再套一层令牌桶（RateLimiter），桶容量 = 云端 QPS， refill 速率 = 1/秒。Java 示例：
RateLimiter limiter = RateLimiter.create(150); // 与云端一致
if (limiter.tryAcquire()) {
callYoudaoAPI();
} else {
sleep(200); // 退避 200 ms 后重试
}
退避策略采用「全抖动 + 指数增长」，最大 3 次，能把 90% 的 429 消在本地，避免直接抛给用户。
常见分支：批量文件与实时对话如何共存
同一应用下若既有「批量文档整翻」又有「直播同传字幕」，建议拆成两个应用 ID：批量任务给低 QPS（如 20），实时任务给高 QPS（如 200）。通过「应用级」隔离，可确保批量突刺不会挤占实时通道。
警告：官方暂不支持「子路径级」限流，若必须单应用，请自行在网关层按 URL 路径做二次分发，否则实时业务仍可能被批量任务拖垮。
监控与验收：三条指标看板
- 控制台「流量分析」→ 429 次数占比 < 0.1% 为健康。
- 业务日志→ 平均重试次数 < 0.3 次/请求。
- 账单→ 因重试带来的额外调用量增幅 < 5%。
连续两周达成以上三点，即可认为限流策略落地成功。
版本差异与迁移建议
2026 年 3 月之前创建的老应用默认「无上限」，升级至 10.8.0 版 SDK 后不会强制收回，但控制台会弹出「建议设置 QPS」横幅。若业务已稳定，可趁低峰期一次性把上限调到「峰值×1.5」；若业务仍在爬坡，可先设「峰值×2」，四周后再收紧。
故障排查：遇到 429 先查这三处
| 现象 | 最可能原因 | 验证动作 | 处置 |
|---|---|---|---|
| 整点批量任务集中报错 | 云端 QPS 上限低于本地并发 | 对比日志并发数与控制台数值 | 上调上限或降低本地线程池 |
| 间歇性 429，无规律 | 同账户其他应用抢量 | 控制台「账户总览」→ 分应用 429 曲线 | 为各应用分别设独立上限 |
| 升级 SDK 后突然 429 | 新 SDK 默认开启「连接复用」导致瞬时突刺 | 抓包看是否出现多请求复用同一连接 | 在初始化参数关闭 http2 multiplex |
适用/不适用场景清单
- 适合：跨境直播、同传字幕、批量文档、政务内网离线翻译等可预测峰值场景。
- 不适合：需要「突发大流量+零延迟」的秒杀类活动；此时应提前 48 小时发邮件申请临时白名单，否则限流无法临时解除。
最佳实践 5 条速查表
- 先买「资源包」再设「QPS 上限」，避免上限高于余量导致额外扣费。
- 同一账户下不同业务必须拆应用，忌共用 AppKey。
- 控制台改完上限后，本地 SDK 需重启长连接，否则旧节点仍按旧配额。
- 令牌桶容量不要 > 云端 QPS，否则本地桶通过，云端仍 429。
- 每月第一天把过去 30 天 429 占比导出 CSV，连续上升就提前扩容，别等用户投诉。
FAQ
QPS 上限可以设小数吗？
控制台仅接受整数，最小为 1。若需要 0.5 次/秒，可在本地用令牌桶做二倍间隔，即每 2 秒允许 1 次。
生效时间到底多久？
官方文档声明「1–2 分钟」。经验性观察：国内三大运营商网络平均 45 秒，教育网 IPv6 可能 3 分钟，建议以 2 分钟为基准做健康检查。
429 报错会影响账户权重吗？
不会。429 仅拒绝当前请求，不写入信用记录。但若持续一周 429 占比 > 5%，客服可能发邮件提醒「配置不合理」，仍不会降权。
能否临时关闭限流？
控制台不提供「暂停」按钮，只能把上限调到账户最大可购值。如需临时超大流量，请提前申请白名单并购买对应资源包。
设置错误导致无法调用，如何快速回退？
立刻把 QPS 上限改回 0（代表恢复账户默认），保存后 2 分钟内生效；若仍报错，检查是否同时触发了「当日资源包用完」。
下一步行动
登录控制台按「峰值×1.5」先设一个安全值，再在本地 SDK 加令牌桶与退避重试，跑两周后把 429 占比压到 0.1% 以下，就算真正告别超限报错。后续每月例行回顾一次曲线，随业务增长逐步收紧，既省费用也保稳定。