> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 常见错误码
> 汇总调用钉钉服务端通讯录接口的常见问题,涵盖 userId 与 unionId 区别、获取用户 Token 未返回 corpId、获取全部员工信息、个人通讯录未返回邮箱以及清除部门主管等场景。
## userId 和 unionId 的具体场景区别
答：userId和unionId的具体场景区别如下：
1. 用户的userid在同一企业下是全局唯一的，不会出现重复现象；
2. 用户的unionId在同一个应用服务内是全局唯一的。例如，小钉同时在三个企业内，共用了同一个第三方企业应用，通过该第三方企业应用获取小钉的信息，unionId是相同的。
3. 通过userId可以查询对应unionId，请参见[查询用户详情](/zh/open/development/query-user-details)。反之通过unionId也查询对应的userId，请参见[根据unionid获取用户userid](/zh/open/development/query-a-user-by-the-union-id)。
## 调用获取用户Token接口未返回corpId
答：调用[获取用户token](/zh/open/development/obtain-user-token)接口出现上述问题可能原因如下:
在[获取登录用户的访问凭证](/zh/open/development/obtain-identity-credentials)进行构造登录授权页面时需传上scope=openid%20corpid 授权后取到authcode再获取用户Token即可返回corpid。
## 如何获取企业全部员工信息
答：钉钉尚未提供获取企业全部员工信息接口，开发者可以通过以下方式获取企业全部员工信息，详细流程可参考获取企业下所有员工信息使用案例。
1. 可以先调用获取部门列表接口，获取到该企业下所有部门ID。
2. 遍历调用[获取部门用户userid列表](/zh/open/development/query-the-list-of-department-userids)接口。
确保通讯录接口权限为**全部员工**。
## 调用获取用户个人通讯录信息接口未返回邮箱
答：调用[获取用户通讯录个人信息](/zh/open/development/dingtalk-retrieve-user-information)接口出现上述问题可能原因如下：
在钉钉客户端-邮箱里有设置的邮箱才会返回邮箱数据(如下图所示)
钉钉提供的邮箱(例如:[xxx@dingtalk.io](mailto:xxx@dingtalk.io))不返回邮箱数据。
## 如何清除用户信息中部门主管
答：调用[更新用户信息](/zh/open/development/user-information-update)接口清除部门主管的方式如下：
清空部门主管传参force\_update\_fields(强制更新字段)设置dept\_manager\_userid\_list(部门主管)，不要传dept\_manager\_userid\_list为空，否则会出现异常。
## 调用查询用户详情接口，无法获取用户手机号
答：调用[查询用户详情](/zh/open/development/query-user-details)接口出现上述错误原因可能为：接口权限不足。
解决方案：在[钉钉开发者后台](https://open-dev.dingtalk.io/#/)，打开该应用详情，找到接口权限入口，申请开通里面获取手机号信息的权限。
## 关于报错“请求的用户userid/部门id不在授权范围内”的说明
* 若为企业内部应用：请在开发者后台进入对应应用的权限管理界面，确认是否已经将对应的部门或人员添加到授权权限范围中。
* 若为第三方企业应用：则需要授权企业（即开通使用该应用的企业）在[钉钉管理后台](https://oa.dingtalk.io/) **> 工作台 > 应用管理**，选择对应三方应用，并点击设置按钮。在弹出的界面中，确认是否已经将对应的人员添加到可见范围中。
## 调用通讯录接口报错 `errcode 50002 请求的员工 userid 不在授权范围内`
答：请求接口 accessToken 对应的应用，在开发者后台**权限管理**页面的授权范围内不包含该员工。
解决方案：单击权限管理的**添加**按钮，将该用户添加到**授权人员**中。
## 调用通讯录接口报错 `errcode 50004 请求的部门 id 不在授权范围内`
答：请求接口 accessToken 对应的应用，在开发者后台**权限管理**页面的授权范围内不包含该部门。
解决方案：单击权限管理的**添加**按钮，将需要变更的部门添加到**授权人员**中。
## 调用更新用户信息报错 `errcode 40022 企业中的手机号码和登录钉钉的手机号码不一致`
答：调用[更新用户信息](/zh/open/development/user-information-update)接口出现上述错误原因为：接口暂时不支持修改用户手机号，可以删除后重新添加。
## 调用根据手机号查询用户报错 `errmsg 无权限调用`
答：调用[根据手机号查询用户](/zh/open/development/query-users-by-phone-number)接口出现上述错误原因可能为：应用版本过老（使用 corpId 和 Corpsecret 获取 accessToken 的应用）。
解决方案：需要创建新应用获取。
## 调用创建用户报错 `errmsg 系统繁忙`
答：调用[创建用户](/zh/open/development/user-information-creation)接口出现上述错误原因可能如下：
可能是企业添加员工超出每周添加人数上限，或者是超出企业添加人数上限。
## 调用创建用户报错 `errcode 60103 手机号码不合法`
答：调用[创建用户](/zh/open/development/user-information-creation)接口出现上述报错时，其可能原因包括但不限于以下几点：
* 在钉钉中设置的公司地区是非中国大陆地区，若手机号为中国大陆地区，请使用+86-xxxxxx。
* 在钉钉中设置的公司地区是中国大陆地区，若手机号为非中国大陆地区，请使用+86-xxxxxx。
## 调用创建用户返回"errcode: 40103, errmsg: 已发出邀请，对方同意后即可加入组织"
答：在调用[创建用户](/zh/open/development/user-information-creation)接口邀请用户加入组织时，若出现上述返回信息，可能原因包括但不限于以下情况:
* 命中安全规则：如果一个员工已经在认证企业A，此时B企业再添加该员工时就会有上述提示。请在客户端搜索团队邀请或者在通讯录界面查看对应的邀请信息并进行相应处理。
* 被邀请的用户在钉钉手机客户端-我的-设置-隐私-团队与成员中启用了“团队添加我时需要验证”，开启后请在客户端搜索团队邀请或者在通讯录界面查看对应的邀请信息并进行相应处理。
用户同意并成功加入企业后，若当天企业删除该用户，则删除后24小时内再次调用接口邀请该用户时，也会返回上述错误信息。
## 调用添加外部联系人报错 `errmsg 系统繁忙 errcode 40001`
答：调用[添加外部联系人](/zh/open/development/add-enterprise-external-contacts)报上述错误可能原因是企业在外部联系人里面添加了自定义字段，并且设置为必填。可以修改这个自定义字段的必填选项为“否”，或者添加外部联系人时添加此字段信息。
## 调用获取用户个人通讯录信息接口报 `Forbidden.AccessDenied.AccessTokenPermissionDenied 没有调用该接口的权限`
答：调用[获取用户通讯录个人信息](/zh/open/development/dingtalk-retrieve-user-information)接口出现上述错误时，其可能原因包括但不限于以下几点：
* 权限问题：需要检查"通讯录个人信息读权限"和"个人手机号信息"是否已申请。
* 接口凭证accessToken有误：该接口的授权凭证为个人用户的accessToken，若传入的accessToken不对也会产生上述报错。获取个人用户的accessToken步骤如下：
**第1步**：获取authCode。浏览器访问构造出的登录授权页面地址：[https://login.dingtalk.io/oauth2/auth?redirect\_uri=https%3A%2F%2Fwww.aaaaa.com%2Fa%2Fb（示例并非固定uri）](https://login.dingtalk.io/oauth2/auth?redirect_uri=https%3A%2F%2Fwww.aaaaa.com%2Fa%2Fb（示例并非固定uri）) //授权通过/拒绝后回调地址，确保已经添加至开发者后台对应应用中登录与分享-回调域名中。\&response\_type=code //固定值为code，授权通过后返回authCode。
\&client\_id=dingbbbbbbb //应用appkey
\&scope=openid%2Bcorpid
\&state=dddd
\&prompt=consent
用户点击进行授权后，会跳转到[https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd](https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd) 通过该地址即可获取authCode。
**第2步**：获取到的authCode后，通过调用[获取用户token](/zh/open/development/obtain-user-token)获取个人用户的accessToken。详情可以查看[获取登录用户的访问凭证](/zh/open/development/obtain-identity-credentials)。
## 调用更新/删除/查询用户报错 `errcode 60121 找不到该用户`
答：出现上述错误时可能原因包括但不限于以下情况：
* 传参userId(用户在企业中唯一标识)与传参access\_token(服务端API访问凭证)所对应的应用不在同一个企业。
* 传参userId(用户在企业中唯一标识)的用户为已离职状态或待入职状态。
* 企业邀请该用户后，用户暂未同意加入企业导致。
## 调用获取部门详情报错 `errcode 40009 不合法的部门 id`
答：调用[获取部门详情](/zh/open/development/query-department-details0-v2)接口出现上述错误可能原因如下：
传参dept\_id为-7(-7是家校通讯录部门ID)，家校通讯录dept\_id=-7不支持调用通讯录管理场景文档。
## 调用更新用户信息报错 `errcode 12150 已开启智能人事职位管理`
答：调用[更新用户信息](/zh/open/development/user-information-update)接口出现上述错误可能原因如下：
已开启智能人事职位管理的场景，若需更新用户信息中职位(title)或部门(deptid)就需要根据智能人事员工调岗来更新。