SaaS API接口报错401排查流程

1、背景

为确保接口调用安全性，开放网关接口需要鉴权通过后才会正常响应。

通过开放网关调用报错401是指接口鉴权失败，鉴权方式包括：OAuthToken鉴权方式和签名鉴权方式，导致鉴权失败的原因比较多。本文将针对各情况进行具体分析。

2、鉴权方式对比

根据请求头里的"X-Tsign-Open-Auth-Mode"参数控制，值为 "Signature"表示使用签名鉴权模式，如果没有指定该请求头，默认为OAuthToken鉴权模式。

3、常见场景分析

场景一：缺少参数

接口响应

{"success":false,"code":401,"message":"缺少参数"}

排查方法及解决方案

TOKEN鉴权模式下请检查请求头中必填参数：X-Tsign-Open-App-Id；

签名鉴权模式下请检查请求头中必填参数：X-Tsign-Open-Ca-Timestamp、X-Tsign-Open-Ca-Signature、X-Tsign-Open-App-Id确保都有传值。

场景二：AUTHSTRATEGY_NOT_FOUND

接口响应

{"success":false,"code":401,"message":"AUTHSTRATEGY_NOT_FOUND"}

排查方法及解决方案

X-Tsign-Open-Auth-Mode值不符合规则，签名鉴权模式需传入X-Tsign-Open-Auth-Mode = "Signature", TOKENE方式无需传入该值。

场景三：无效的应用

接口响应

{"success":false,"code":401,"message":"无效的应用"}

排查方法及解决方案

该报错两种鉴权方式均可能出现。

• 检查appid是否正确，且与接口调用域名所属环境是否一致。

正式环境域名：https://openapi.esign.cn , 正式环境appid一般是5111开头的

沙箱环境域名：https://smlopenapi.esign.cn, 沙箱环境appid一般是7438或者4438开头的

• 检查appid状态是否开启，被禁用时也会导致该报错，可登录开放平台（https://open.esign.cn/）进行查看

场景四：TOKEN错误

接口响应

{"success":false,"code":401,"message":"TOKEN错误"}

排查方法及解决方案

TOKEN鉴权模式下传入的TOKEN非该应用id下获取, 或者TOKEN过期（注：TOKEN有效期默认为120分钟，重复获取TOKEN会导致之前TOKEN提前失效），需重新获取新的TOKEN。TOKEN提前失效一般出现于多服务器分布式部署场景，多台服务分别获取TOKEN导致。

场景五：TOKEN_CANT_BE_NULL

接口响应

{"success":false,"code":401,"message":"TOKEN_CANT_BE_NULL"}

排查方法及解决方案

TOKEN鉴权模式下请求头内没有传入TOKEN导致，需在请求头里传入X-Tsign-Open-Token参数及对应值。

场景六：INVALID_TIMESTAMP

接口响应

{"success":false,"code":401,"message":"INVALID_TIMESTAMP"}

排查方法及解决方案

请检查请求头中的时间戳：X-Tsign-Open-Ca-Timestamp 字段，需要确保是15分钟内的毫秒级时间戳。常见于客户服务器时间不是北京时间。在线时间戳转换工具：https://tool.chinaz.com/tools/unixtime.aspx

场景七：INVALID_SIGNATURE

接口响应

{"success":false,"code":401,"message":"INVALID_SIGNATURE"}

排查方法及解决方案

造成INVALID_SIGNATURE（无效的签名）的根本原因是请求头中的签名值计算不正确，可以使用开放平台鉴权签名计算工具进行排查。

签名计算错误可能原因如下：

（1）请检查计算签名时用的secret与appId和接口环境是否匹配一致，是否存在空格。

（2）请检查计算签名时用的JSON字符串与实际请求发送的JSON字符串是否一致（是否前后JSON格式化不一致）。

（3）待签字符串拼接错误：

• 请检查请求头中Key值和Value值与待签字符串中的是否一致，重点检查Content-MD5、Accept、Content-Type。
• 待签字符串中拼接的url参数不要带域名。
• url中query参数存在中文值的情况下（比如关键字查询接口），为了避免乱码情况，需要在请求时对该参数值进行urlencode编码，注意：待签字符串拼接时不能编码。
• url地址中如果存在query参数，需要按照字典顺序排序