前言
调用大疆司空 2OpenAPI接口时，很多开发者都会遇到403 无权限异常这个问题。本文基于实际项目排错经验，整理了完整的排查步骤，帮助你快速定位并解决问题。
403 错误是大疆 OpenAPI 开发中最常见的问题之一，据统计，超过 90% 的 403 错误都是由几个常见原因导致的。按照本文的步骤一步步检查，基本上都能解决问题。
如果你还没开始接入，可以先阅读前篇：大疆司空平台接入实战：Java SDK 开发指南
一、问题现象
调用大疆司空 OpenAPI 接口时，客户端收到 HTTP 响应码401403，响应消息类似如下：
{"code":"200401","message":"Unauthorized"}或者：
{"code":"200403","message":"Forbidden","data":null}接口调用失败，无法获取数据。
二、排查步骤总览
按照以下顺序逐一检查，可以最快定位问题：
- 检查 Token 生成人是否在项目中
- 检查用户权限是否足够
- 检查请求头是否携带
X-Project-Uuid - 检查
X-Project-Uuid格式是否正确 - 检查域名是否与区域匹配
- 检查 IP 白名单配置
提示：90% 的问题出现在前 three 步，建议重点检查。
三、检查 Token 生成人是否在项目中
Token 是与创建用户绑定的，如果用户不在项目中，Token 会自动失效。这是最常见的 403 原因。
检查步骤：
- 登录 大疆司空管理后台
- 进入你的项目，点击「项目设置」
- 选择「项目成员」标签页
- 在成员列表中搜索生成 Token 的用户名
- 确认用户仍然在成员列表中
常见场景：
- 生成 Token 的员工已经离职，被移除出项目
- 项目交接后，原来的创建人不再参与该项目
- 误操作将用户从项目成员中移除
解决方法：
如果用户已经不在项目中，需要由现有项目管理员重新生成 Token。
四、检查用户权限是否足够
生成 Token 的用户必须具有项目管理员权限，否则无法调用 OpenAPI。这是第二常见的原因。
检查步骤：
- 在项目成员列表中找到该用户
- 查看用户角色列显示的角色
- 确认角色是「项目管理员」
| 角色 | 是否能调用 OpenAPI |
|---|---|
| 项目管理员 | ✅ 可以 |
| 普通成员 | ❌ 无权限 |
| 查看者 | ❌ 无权限 |
解决方法：
如果权限不足，请联系项目管理员提升权限，或者由管理员直接生成 Token。
提示：即使你是企业管理员，也需要在具体项目中被授予项目管理员权限才能调用 API。
五、请求头必须携带 X-Project-Uuid
大多数项目相关的 OpenAPI 接口都需要在请求头中携带项目 UUID，否则会直接返回 403。
5.1 正确示例
// Java OkHttp 示例requestHeaders.put("X-User-Token","your-access-token");requestHeaders.put("X-Project-Uuid","xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");// JavaScript Axios 示例axios.get('/api/proxy',{headers:{'X-User-Token':'your-access-token','X-Project-Uuid':'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'}});5.2 常见错误
| 错误类型 | 错误示例 | 正确写法 |
|---|---|---|
| 大小写错误 | x-project-uuid | X-Project-Uuid |
| 缺少连字符 | XProjectUuid | X-Project-Uuid |
| 错误单词 | X-Project-UUID | X-Project-Uuid |
| 放在参数里 | ?X-Project-Uuid=xxx | 必须放在请求头 |
六、获取正确的项目 UUID
如果你不知道项目 UUID 是什么，调用以下接口可以获取当前 Token 有权限访问的所有项目列表：
GET https://es-flight-api-cn.djigate.com/openapi/v0.1/project Headers: X-User-Token: your-token-here响应示例：
{"code":0,"message":"success","data":{"projects":[{"uuid":"12345678-1234-1234-1234-123456789abc","introduction":"预置航线、照片、模型和地图标注等，辅助了解司空2 功能。","name":"电力巡检项目","created_at":"2026-01-01T00:00:00Z"},{"uuid":"87654321-4321-4321-4321-cba987654321","introduction":"","name":"光伏电站巡检","created_at":"2026-02-01T00:00:00Z"}]}}从响应中取出uuid字段，就是你需要填入请求头的X-Project-Uuid。
七、检查域名与区域匹配
大疆司空在不同区域有不同的接入域名，如果区域不匹配也会返回 403。
域名对应表：
| 区域 | API 域名 | 使用场景 |
|---|---|---|
| 中国区 | es-flight-api-cn.djigate.com | 中国大陆用户 |
| 海外区 | es-flight-api.djigate.com | 海外用户 |
重要提示：如果你的账号注册在中国区，必须使用
*-cn.djigate.com域名，否则会返回 403。
八、检查 IP 白名单配置
如果你的应用配置了IP 白名单，只有白名单内的 IP 地址才能调用 API。
检查步骤：
- 进入「企业管理」→「开发者」
- 打开你的应用配置页面
- 查看是否配置了 IP 白名单
- 确认你调用 API 的服务器 IP 在白名单中
解决方法：
如果你的服务器 IP 发生了变化，需要更新 IP 白名单配置。
九、完整检查清单
打印出来，排查的时候一项一项打勾：
| 检查项 | 检查结果 | 说明 |
|---|---|---|
| Token 生成人在项目成员列表中 | □ | 移除/离职需要重新生成 |
| Token 生成人是项目管理员 | □ | 普通成员无 API 调用权限 |
请求头包含X-Project-Uuid | □ | 注意大小写和拼写 |
X-Project-Uuid是正确的 UUID 格式 | □ | 不能使用项目名称或其他ID |
域名与区域匹配（中国区使用*-cn.djigate.com） | □ | 区域不匹配也会导致 403 |
| 服务器 IP 在白名单中 | □ | 配置了白名单的需要检查 |
| Token 没有过期 | □ | Token 创建后永久有效，除非重新生成 |
| Token 没有被撤销 | □ 在开发者中心可以查看 Token 状态 |
十、查看 Token 创建人信息
在大疆司空开发者界面，可以直接查看当前 Token 是由哪个用户生成的：
操作步骤：
- 登录大疆司空管理后台
- 进入「企业管理」→「开发者」
- 找到你的应用，点击「查看」按钮
- 在 Token 管理列表中，可以看到每条 Token 的创建人和创建时间
- 记录创建人用户名，回到项目成员列表核对
截图示例：
图：大疆司空开发者中心 Token 管理界面示例
上图就是 Token 管理界面，可以清楚看到每条 Token 的创建人信息。
十一、快速排查流程图
如果你不确定从哪里开始，按照这个流程图一步步走：
┌─────────────────┐ │ 调用 API 返回 403 │ └────────┬────────┘ ↓ ┌──────────────────────────────────┐ │ Token 创建人在项目成员中吗？ │ │ └─ NO → 请管理员重新生成 Token │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ 用户是项目管理员吗？ │ │ └─ NO → 提升权限或重新生成 │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ 请求头带了 X-Project-Uuid 吗？ │ │ └─ NO → 添加请求头 │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ UUID 格式正确吗？ │ │ └─ NO → 调用项目列表接口获取 │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ 域名选择正确了吗？ │ │ └─ NO → 中国区换 *-cn.djigate.com │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ IP 在白名单中吗？ │ │ └─ NO → 添加IP到白名单 │ └────────┬─────────────────────────┘ ↓ YES ┌──────────────────────────────────┐ │ 问题解决！🎉 │ └──────────────────────────────────┘按照这个流程走一遍，99% 的问题都能解决。
总结
大疆 OpenAPI 返回403 无权限异常，90% 以上都是由以下三个原因导致：
Top 3 原因：
- Token 创建人不在项目中——解决方法：重新生成 Token
- Token 创建人不是管理员——解决方法：提升权限或换管理员生成
- 缺少 X-Project-Uuid 请求头——解决方法：添加正确的项目 UUID
如果这三点都检查过了还是不行，再依次检查域名、IP 白名单等其他可能性。
按照本文的步骤一步一步检查，基本都能解决问题。下一篇文章我会分享大疆司空 Webhook 事件接收的坑点和解决方案，感兴趣的话欢迎关注。
如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！
相关资源：
- 大疆开发者平台
- 大疆司空官网
- 大疆司空 OpenAPI 文档
- 大疆司空平台接入实战指南
