# 服务端 API 问题定位与解决

为了减少出现调用服务端 API 错误，开发者应该使用正确的 Token，应该认真阅读接口文档，按照接口文档的参数描述正确传参，以及还需认真阅读接口文档中的注意事项等。

开发者如遇到服务端接口报错问题可优先使用 API 报错诊断工具进行自助诊断，如果问题仍无法解决，可前往开放社区发帖反馈，发帖时务必提供接口报错返回的 rid。

API 报错诊断工具使用指引可查看：接口报错诊断

# 1、如何确认微信后台接收的请求参数

当调用接口出现了例如「格式不对」、「缺少 XX 参数」等问题时，如果自认为传参正确且完整，但是接口依旧报错时，建议开发者可使用 查询 rid 信息（该接口适用于小程序、小游戏、公众号、服务号、微信小店、带货助手、联盟带货机构、视频号助手、第三方平台、移动应用、网站应用等账号）接口，通过该接口可以清晰获知你当次的请求传到微信后台的参数情况。

此外，可使用 API 报错诊断工具进行诊断：

# 2、无权限调用接口（错误码：48001 或 61007）

和权限有关的报错常见的 errmsg 关键字为 api unauthorized 或 api is unauthorized，以及常见的错误码为 48001 和 61007，如遇到 48001 和 61007 报错问题，请按照下方指引进行自助排查。

# 2.1 错误码 48001

返回示例：{"errcode":48001,"errmsg":"api unauthorized, rid: xxx"}

出现 48001 错误的原因有两大类：

调用接口的时候 Token 传错了

• 通常是把公众号/服务号/小程序/小游戏/小店/小店带货助手/视频号助手等账号的 access_token、第三方平台的 component_access_token、第三方平台的 authorizer_access_token 搞错了
• 例如，某接口是小程序的接口，然后传了用公众号生成的 authorizer_access_token 或者 access_token
• 例如某接口是小店的接口，然后传了用小程序生成的 authorizer_access_token 或者 access_token
• 所以出现 48001 错误的时候首先自查一下调用接口用的账号和接口的适用范围是否匹配的

API 功能未授权

• 有些接口只开放给已认证的账号，如果使用未认证的账号调用，则会返回没权限的提示
• 有些功能接口需要在公众平台或者小店平台等控制台单独进行开通之后才获得调用权限的，需开发者自查当前调用的 API 是否属于这种情况
• 如果调用的 API 是只开放给第三方平台代公众号/服务号/小程序/小店/带货助手/视频号助手等账号调用的，那么公众号/服务号/小程序/小店/小店带货助手/视频号助手等账号本身是没有权限的，而如果第三方平台代调用时也返回了 48001，那么则是公众号/服务号/小程序/小店/小店带货助手/视频号助手等账号尚未将对应的权限集授权给该第三方平台，需要在完成授权后调用

# 2.2 错误码 61007

返回示例：{"errcode":61007,"errmsg":"api is unauthorized to component rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

出现 61007 错误的原因主要是：公众号/服务号/小程序/小店/小店带货助手/视频号助手等账号尚未将对应的权限集授权给第三方平台。

1）服务商如何验证该账号是否已经将对应的权限集授予第三方平台？

可通过调用 getAuthorizerInfo 接口查询，返回的 func_info 中是否包含了对应的权限 id。

2）如何查询调用的接口隶属于哪个权限集 id？

可查阅权限集说明文档。以及在接口文档中通常也会写该接口所属的权限集 id 信息，如下图：

# 3、无权限调用接口（错误码：61003）

返回示例：{"errcode":61003,"errmsg":"component is not authorized by this account, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

• 如小程序登录接口，当 appid 尚未授权给 component_appid，就会出现 61003 报错
• 服务商应该存一份授权账号信息（可通过调用 getAuthorizerInfo 接口查询），然后就可以知道调用接口传的 appid 是否在授权账号列表里

# 4、reach max api daily quota limit（错误码：45009）

返回示例：{"errcode":45009,"errmsg":"reach max api daily quota limit rid: xxxxxxxx-xxxxxxxx-xxxxxxxxx"}

• 出现该报错表示该账号调用当前接口的当天次数用完了。即，接口请求次数有限制的，开发者可调用 getApiQuota 接口获取接口每日调用次数
• 如果出现该问题了，开发者可调用重置 API 调用次数或者调用重置指定 API 调用次数进行清空（该接口同样适用于第三方平台代其调用）
• 补充：重置 API 调用次数与重置指定 API 调用次数接口的调用，可使用 access_token、component_access_token 和 authorizer_access_token 调用；请注意不要使用错误的 Token 进行调用
• 同时也适用于用来清理获取 access_token、component_access_token 和 authorizer_access_token 的调用次数，使用其对应的 Token 进行调用即可
• 另外，如果是生成 Token 的接口次数不够了，还可以通过 appid 和 secret 来重置调用次数，详情可查看使用 AppSecret 重置 API 调用次数

# 5、user limited（错误码：50002）

返回示例：{"errcode":50002,"errmsg":"user limited rid: xxxxxxxx-xxxxxxxx-xxxxxxxxx"}

• 通常是该小程序/小游戏/公众号/服务号等账号被冻结了、注销了或者迁移了。可以使用手机扫该公众号/服务号或者小程序码进行验证即可
• 此外，50007 的错误码则是账号冻结了，详情可查看公众账号被系统冻结问题汇总

# 6、access clientip is not registered（错误码：61004 或 40164）

返回示例：

• {"errcode":61004,"errmsg":"access clientip is not registered requestIP: 119.147.XX.170 rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

出现此问题时，需要将报错信息中的 IP 地址添加到 API IP 白名单中。各业务的白名单配置路径如下：

• 第三方平台：微信开放平台 - 管理中心 - 第三方平台 - 详情 - 开发配置 - 开发资料

• 公众号/服务号/带货助手：微信开发者平台 - 我的业务 - 公众号/服务号/带货助手 - 基础信息 - 开发信息

• 小程序/小游戏：微信公众平台 - 开发管理 - 开发设置 - 开发者 ID - IP 白名单

• 微信小店：微信小店 - 服务市场 - 经营工具 - 自研

• 视频号助手：视频号助手 - 直播 - 直播管理 - 开放能力 - 基础信息

# 7、access_token 无效或不是最新

与 access_token 有关的错误码以及返回示例如下：

• {"errcode":42001,"errmsg":"access_token expired rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":40001,"errmsg":"invalid credential, access_token is invalid or not latest rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":40014,"errmsg":"invalid access_token rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

# 7.1 原因解释

• 错误码 42001 表示 access_token 已过期，需重新获取
• 错误码 40001 表示 access_token 无效或不是最新的，通常原因为其他业务逻辑同时也在获取该账号的 access_token，导致当前 access_token 被刷新了无效了，需重新获取
• 错误码 40014 表示 access_token 无效，需重新获取

# 7.2 解决方案

1）使用 getAccessToken 或者 getStableAccessToken 接口获取新的 access_token，并且将新的 access_token 存入存储

2）参考 access_token 使用说明文档正确地存储并使用 access_token

# 8、must use component token（错误码：61014）

返回示例：{"errcode":61014,"errmsg":"must use component token for component api rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 61014 表示调用第三方平台接口时使用了错误的 Token 类型，如使用了 access_token 或者 authorizer_access_token 调用，应该改为使用 component_access_token 调用第三方平台的 API。

# 9、refresh_token is invalid（错误码：61023）

返回示例：{"errcode":61023,"errmsg":"refresh_token is invalid rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 61023 表示 refresh_token 无效，需重新调用 getAuthorizerList 获取所有已授权账号的 authorizer_refresh_token。

# 10、api minute-quota reach limit（错误码：45011）

返回示例：{"errcode":45011,"errmsg":"api minute-quota reach limit, must slower, retry next minute rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 45011 表示每分钟调用频率过高，需控制每分钟的调用频率。

# 11、appid 缺失或错误

与 appid 有关的错误码以及返回示例如下：

• {"errcode":41002,"errmsg":"appid missing rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":40013,"errmsg":"invalid appid rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":41018,"errmsg":"missing component_appid rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

原因解释

• 错误码 41002 表示调用接口时，appid 是必传的参数，但是实际调用的时候未传入该参数，按照接口文档要求传入正确的 appid 即可
• 错误码 40013 表示调用接口时，传入了不正确的 appid，按照接口文档要求传入正确的 appid 即可
• 错误码 41018 表示调用接口时，component_appid 是必传的参数，但是实际调用的时候未传入该参数，按照接口文档要求传入正确的第三方平台 appid 即可

此外，可使用 API 报错诊断工具进行诊断，可查看到实际传入的 appid。

常见的需要传入 appid 或者 component_appid 接口如下：

# 12、appsecret 缺失或错误

与 appsecret 有关的错误码以及返回示例如下：

• {"errcode":40125,"errmsg":"invalid appsecret rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":41004,"errmsg":"appsecret missing rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

原因解释

• 错误码 41004 表示调用接口时，secret 或 appsecret 是必传的参数，但是实际调用的时候未传入该参数，按照接口文档要求传入正确的 secret 或 appsecret 即可
• 错误码 40125 表示调用接口时，传入了不正确的 secret 或 appsecret，按照接口文档要求传入正确的 secret 或 appsecret 即可

此外，可使用 API 报错诊断工具进行诊断，可查看到实际传入的 secret 或 appsecret。

常见的需要传入 secret 或 appsecret 接口如下：

# 13、code 相关问题

返回示例：

• {"errcode":40029,"errmsg":"invalid code, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":40163,"errmsg":"code been used, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}
• {"errcode":41008,"errmsg":"missing code, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

解释说明：

• 错误码 40029 表示调用接口时，code 参数中传入的 code 不正确，需按照接口文档说明输入正确的 code
• 错误码 40163 表示调用接口时，code 参数中传入的 code 已经被消费过了，不可以重复再使用，需按照接口文档说明获取新的 code 并重新发起请求
• 错误码 41008 表示调用接口时，code 是必传的参数，但是实际调用的时候未传入该参数，按照接口文档要求传入正确的 code 即可

常见的需要传入 code 接口如下：

# 14、invalid grant_type（错误码：40002）

返回示例：{"errcode":40002,"errmsg":"invalid grant_type, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 40002 表示调用接口时，grant_type 传错了值，需按照接口文档传入 client_credential 或者 authorization_code 或者 refresh_token。

常见的需要传入 grant_type 只能填 authorization_code 的接口如下：

常见的需要传入 grant_type 只能填 client_credential 的接口如下：

常见的需要传入 grant_type 只能填 refresh_token 的接口如下：

# 15、invalid oauth code（错误码：40242）

返回示例：{"errcode":40242,"errmsg":"invalid oauth code, it is miniprogram jscode, please use jscode2session, rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 40242 表示调用授权登录接口时，传错了 code 的值，将小程序登录接口 wx.login 返回的 js_code 传入了服务号网页应用、移动应用、网站应用授权登录接口所需的 code。

如果使用 wx.login 返回的 js_code，则应当使用 code2Session 或者 thirdpartyCode2Session 去消费该 code。

# 16、invalid openid（错误码：40003）

返回示例：{"errcode":40003,"errmsg":"invalid openid rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}

错误码 40003 表示调用接口时，传入了不正确的 openid，需按照接口文档获取正确的 openid 重新调用即可。

常见的需要传入 openid 接口如下：