大疆司空平台接入实战：OpenAPI无权限异常排查

前言

调用大疆司空 2 OpenAPI 接口时，很多开发者都会遇到 403 无权限异常 这个问题。本文基于实际项目排错经验，整理了完整的排查步骤，帮助你快速定位并解决问题。

403 错误是大疆 OpenAPI 开发中最常见的问题之一，据统计，超过 90% 的 403 错误都是由几个常见原因导致的。按照本文的步骤一步步检查，基本上都能解决问题。

如果你还没开始接入，可以先阅读前篇：大疆司空平台接入实战：Java SDK 开发指南

一、问题现象

调用大疆司空 OpenAPI 接口时，客户端收到 HTTP 响应码 401 403，响应消息类似如下：

{
  "code": "200401",
  "message": "Unauthorized"
}

或者：

{
  "code": "200403",
  "message": "Forbidden",
  "data": null
}

接口调用失败，无法获取数据。

二、排查步骤总览

按照以下顺序逐一检查，可以最快定位问题：

1. 检查 Token 生成人是否在项目中
2. 检查用户权限是否足够
3. 检查请求头是否携带 X-Project-Uuid
4. 检查 X-Project-Uuid 格式是否正确
5. 检查域名是否与区域匹配
6. 检查 IP 白名单配置

提示：90% 的问题出现在前 three 步，建议重点检查。

三、检查 Token 生成人是否在项目中

Token 是与创建用户绑定的，如果用户不在项目中，Token 会自动失效。这是最常见的 403 原因。

检查步骤：

1. 登录 大疆司空管理后台
2. 进入你的项目，点击「项目设置」
3. 选择「项目成员」标签页
4. 在成员列表中搜索生成 Token 的用户名
5. 确认用户仍然在成员列表中

常见场景：

• 生成 Token 的员工已经离职，被移除出项目
• 项目交接后，原来的创建人不再参与该项目
• 误操作将用户从项目成员中移除

解决方法：

如果用户已经不在项目中，需要由现有项目管理员重新生成 Token。

四、检查用户权限是否足够

生成 Token 的用户必须具有项目管理员权限，否则无法调用 OpenAPI。这是第二常见的原因。

检查步骤：

1. 在项目成员列表中找到该用户
2. 查看用户角色列显示的角色
3. 确认角色是「项目管理员」

解决方法：

如果权限不足，请联系项目管理员提升权限，或者由管理员直接生成 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 常见错误

六、获取正确的项目 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。

域名对应表：

重要提示：如果你的账号注册在中国区，必须使用 *-cn.djigate.com 域名，否则会返回 403。

八、检查 IP 白名单配置

如果你的应用配置了 IP 白名单，只有白名单内的 IP 地址才能调用 API。

检查步骤：

1. 进入「企业管理」→「开发者」
2. 打开你的应用配置页面
3. 查看是否配置了 IP 白名单
4. 确认你调用 API 的服务器 IP 在白名单中

解决方法：

如果你的服务器 IP 发生了变化，需要更新 IP 白名单配置。

九、完整检查清单

打印出来，排查的时候一项一项打勾：

十、查看 Token 创建人信息

在大疆司空开发者界面，可以直接查看当前 Token 是由哪个用户生成的：

操作步骤：

1. 登录大疆司空管理后台
2. 进入「企业管理」→「开发者」
3. 找到你的应用，点击「查看」按钮
4. 在 Token 管理列表中，可以看到每条 Token 的创建人和创建时间
5. 记录创建人用户名，回到项目成员列表核对

截图示例：

图：大疆司空开发者中心 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 原因：

1. Token 创建人不在项目中——解决方法：重新生成 Token
2. Token 创建人不是管理员——解决方法：提升权限或换管理员生成
3. 缺少 X-Project-Uuid 请求头——解决方法：添加正确的项目 UUID

如果这三点都检查过了还是不行，再依次检查域名、IP 白名单等其他可能性。

按照本文的步骤一步一步检查，基本都能解决问题。下一篇文章我会分享大疆司空 Webhook 事件接收的坑点和解决方案，感兴趣的话欢迎关注。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• 大疆开发者平台
• 大疆司空官网
• 大疆司空 OpenAPI 文档
• 大疆司空平台接入实战指南