有道翻译API返回“101”错误码如何排查并解决？

101错误码的官方定义与触发场景

有道翻译开放平台把 101 标注为「请求参数异常」。经验性观察表明，九成以上案例集中在四个字段：appKey、q（待译文本）、salt、sign。只要其中任意一项不符合「必填、长度、时序、签名」四规则，网关会直接返回 101，不会走到计费环节，因此也不会产生额外费用。

与 108（余额不足）、202（业务 QPS 超限）等不同，101 属于「客户端可自愈」错误，官方并不记录到服务端的异常日志，所以排查必须依赖本地抓包或日志回显。理解这一点后，就能排除「服务端故障」的猜测，把焦点拉回参数拼装环节。

版本演进：签名算法与必填字段的两次变更

截至当前的最新版本，签名采用「MD5(appKey+q+salt+curtime+密钥)」的 32 位小写串。2024 年 9 月之前的老示例仍使用「MD5(appKey+q+salt+密钥)」，若直接复制旧代码，会因缺少 curtime 导致 101。官方 FAQ 已注明「老算法继续兼容」，但实测若同时缺少 curtime 与 strictMode=true，则返回 101 概率显著增加。

第二次变更在 2025 年 12 月：当 q 长度超过 5000 字节（约 1600 个汉字）时，必须改用「分段翻译」接口，否则单段请求也会触发 101。该限制在文档「附录-字段边界」中标注，但并未在 SDK 注释里高亮，导致大量批量文件翻译场景首次踩坑。

排查清单：七步定位 101 根因

1. 确认 appKey 为 21 位数字字母混合串，前后无空格。
2. 确认 q 采用 UTF-8 且 URL 编码后长度 ≤5000 字节。
3. salt 为 1–32 位随机正整数，禁止硬编码 123456。
4. curtime 为 10 位 Unix 秒级时间戳，与服务器误差 ≤120 s。
5. sign 拼接顺序固定：appKey+q+salt+curtime+密钥，缺一不可。
6. HTTP 头 Content-Type 必须为 application/x-www-form-urlencoded。
7. POST 体中字段顺序无关，但需与签名原文保持一致。

以上任何一步不满足，都会返回 101，且响应体不会给出「具体是哪个字段」的明细。因此建议本地先打印「待签名字符串」与「最终 sign」，再与官方在线校验工具比对，肉眼即可发现错位。

最小可复现示例：Python 3.11

import time, hashlib, requests, urllib.parse
appKey = '你的21位key'
key = '你的32位密钥'
q = 'hello'
salt = str(int(time.time()))
curtime = str(int(time.time()))
sign_raw = appKey + q + salt + curtime + key
sign = hashlib.md5(sign_raw.encode()).hexdigest()
data = {
    'q': urllib.parse.quote(q),
    'from': 'auto',
    'to': 'zh-CHS',
    'appKey': appKey,
    'salt': salt,
    'sign': sign,
    'curtime': curtime
}
r = requests.post('https://openapi.youdao.com/api', data=data, headers={'Content-Type':'application/x-www-form-urlencoded'})
print(r.status_code, r.json())

若返回 {"errorCode":"101"}，把 sign_raw 打印出来复制到官方「签名调试」输入框，可立即看到哪一段缺失或顺序颠倒。

平台差异：Java、Node、Go 常见坑

Java 需显式指定 Charset.UTF_8，否则中文 q 在 Windows 开发机默认 GBK 下被截断，导致签名通过但网关解码失败，仍抛 101。Node 的 axios 若使用 qs.stringify 默认把空格转成 +，而官方示例使用 %20，两者在签名校验阶段被视为不同字符，同样 101。Go 的 url.Values 会把 / 编码成 %2F，若签名原文未同步替换，也会失败。一句话：签名原文必须与提交体「百分号编码后」完全一致。

超时与缓存：为什么有时重试又正常？

本地时钟漂移超过 120 秒时，网关会拒绝请求；但重试前若 NTP 同步完成，第二次就通过。此类「偶发 101」最容易误导开发者认为是网络抖动。可复现验证：手动把系统时间调快 3 分钟，必现 101；调回后自动恢复。建议在服务器端调用时启用 ntpdate 定时任务，或在代码里用阿里云时间 API 获取 curtime，而非本地系统时间。

分段翻译接口：q 超限的替代方案

当 q 超过 5000 字节，应改用 https://openapi.youdao.com/apiv2/trans 分段接口，支持一次最多 100 段，每段 ≤2000 字节。签名算法不变，只是 q 变成 JSON 数组。若继续使用单段接口，101 是预期行为，并非「文档没说清楚」。迁移成本：把长文本按句号切分即可，返回结果带 index 字段，前端按序拼接即可保持上下文。

回退方案：本地缓存与降级词典

对于内部系统，可把常见术语预置为本地缓存，当监测到 101 且确认是参数异常导致，可先返回缓存译文，同时触发钉钉告警。该策略仅适用于「非用户面对面」场景，例如批量技术文档更新。若面向 C 端实时翻译，101 应直接提示「配置异常，请联系管理员」，避免把错误译文暴露给用户。

监控与告警：如何量化 101 频率

在 Prometheus 里新增指标 youdao_api_101_total，每次捕获 errorCode==101 就 +1，并用 rate() 函数观测 5 分钟增长率。经验性观察：当 101 率超过总调用量 0.5%，大概率是批量服务器时钟漂移或密钥轮换脚本 bug。此时优先检查 salt 是否被误写为固定值，其次核对密钥是否带尾部空格。

常见误区：别再把 101 当「签名错误」

官方错误码表里 102 才是「签名无效」，101 是更上层的「参数异常」。这意味着即使签名算对了，只要 q 超长、appKey 多一个空格，也会先报 101。很多开发者看到 101 就反复改签名，结果越改越乱。正确顺序：先核对字段长度与时钟，再检查签名。

FAQ：你必须知道的 5 个细节

总结与下一步行动

101 错误码的核心矛盾不是「签名难」，而是「参数边界」与「本地环境」不一致。先按七步清单逐项打印比对，再引入自动化监控，就能把发生率压到接近零。下一步：把上述 Python 模板纳入单元测试，每次密钥轮换自动跑一遍，让 101 再无机会上线。