错误码说明

石墨文档中台定义了一系列错误码，用于处理对接或使用过程中出现的问题。不同错误码的有不同的含义，这个文档可以帮你快速定位到问题。

如何快速定位错误码

先确认当前能力属于前端 API、后端 API 还是回调协议。

再按错误码前缀定位区间，按完整错误码定位具体条目。

最后回到对应任务页确认调用顺序和业务处理方式。

错误码区间总览

前缀	区间	模块	出现链路	责任方
`1xxxx`	10001 ~ 10015	你的应用回调对接	石墨 SDK 服务端日志、`回调请求错误`事件推送	你的应用回调接口
`2xxxx`	20001 ~ 20005	应用（App）管理	后端 API 响应、控制台	控制台/调用方参数
`3xxxx`	30001 ~ 30008	账号管理	接入账号相关 API 响应	调用方参数、账号状态
`7xxxx`	70015 ~ 70020	协同文档副本任务	后端 API 响应 body 中的 `code` 字段	副本创建任务（可重试或要人工介入）
`9xxxx`	90033 ~ 90052	预览 / 文件下载	预览任务回执	你的应用提供的 `downloadUrl`、文件本身
`12xxxx`	120016 ~ 120509	导入 / 导出	导入导出任务回执	文件类型、大小、内容限制

错误响应格式

后端 API（/sdk/v2/...）发生错误时，HTTP 状态码与 code 字段同时返回。Response Body 的最小结构：

{
  "code": 70019,
  "message": "可读的中文错误说明",
  "requestId": "用于在石墨侧定位日志的 ID"
}

你的应用在排查时，建议把下面这些字段同时写进业务日志：

HTTP 状态码（如 200 / 204 / 400 / 401 / 403 / 404 / 500）。

响应 body 中的 code（错误码）和 message（错误说明）。

X-Request-Id / requestId，必要时反馈给石墨服务方做联合排查。

触发本次请求的 fileId、用户 ID、调用接口路径。

回调链路（石墨 → 你的应用）的错误，会通过 回调请求错误 事件推送到你的应用 endpoint_url，结构见后文回调请求错误事件。

排查清单

按下面 4 步走，90% 的错误码都能定位：

看错误码前缀，确定是回调（1xxxx）、应用/账号管理（2xxxx/3xxxx）、协同副本任务（7xxxx）、还是预览/导入导出（9xxxx/12xxxx）。

看 HTTP 状态码：4xx 多为请求参数问题，5xx 多为服务端临时故障或下游回调出错。

看出现链路：前端事件、后端 API 响应，还是石墨推送过来的 回调请求错误 事件。

看是否可重试：副本任务、导入导出多为异步任务，部分错误重试有效；签名 / 参数错误重试无效。

需要关注的字段

许多接口响应中会经常出现这些字段，整理出来字段的含义如下所示：

字段	类型	出现位置	含义
`code`	integer	API 响应 body / 错误事件	错误码，按下文表查询
`message`	string	API 响应 body	可读错误说明，仅作辅助，不要硬编码做判断
`status`	integer	`/sdk/v2/api/license/users` 返回	用户席位状态：1=激活，0=禁用，-1=未启用
`kind`	string	回调事件 body	事件大类，用于区分推送类型
`action`	string	`collaboratorChanged` 等事件	事件动作，例如 `enter` / `leave`
`clientId`	string	协作事件 body	协作客户端实例 ID
`userId`	string	多处出现	你的应用用户 ID
`fileId`	string	多处出现	你的应用文件 ID
`timestamp`	integer	事件 body	事件产生时间

错误码详细表

1xxxx 你的应用回调对接

发生在「石墨 → 你的应用回调接口」这条链路。典型表现：石墨服务侧日志报错、前端打开文档时报错；你的应用业务后端可能没有直接日志。

错误码	说明	常见 HTTP	可能原因	修复动作	是否可重试
10001	不合法的 endpoint 地址	—	App 配置的回调前缀不正确、含非法字符或协议头	用更新应用信息接口更新 `endpointUrl`，确认带 `https://` 前缀	配置改完即生效，不需重试
10002	获取指定文件信息 404	你的应用返回 404	`GET /files/{fileId}` 未实现或路径不匹配	检查回调路由、`fileId` 命名规则、租户隔离逻辑	修好接口后自动恢复
10003	获取当前用户信息 404	你的应用返回 404	`GET /users/current/info` 未实现或 token 失效	实现接口；用 `X-Shimo-Token` 还原当前用户	修好接口后自动恢复
10004	获取指定用户信息 404	你的应用返回 404	`GET /users/{userId}` 未实现	检查路由和参数命名	修好接口后自动恢复
10005	获取用户信息列表 404	你的应用返回 404	批量查询用户接口未实现	实现 `POST /users/batch` 或类似接口	修好接口后自动恢复
10006	获取协作权限用户列表 404	你的应用返回 404	协作者列表接口未实现	实现 `GET /files/{fileId}/collaborators`	修好接口后自动恢复
10007	搜索最近联系人列表 404	你的应用返回 404	最近联系人接口未实现，@人时报错	实现 `/search/users/recent`	修好接口后自动恢复
10008	搜索最近使用文件列表 404	你的应用返回 404	最近文件接口未实现，@文件时报错	实现 `/search/files/recent`	修好接口后自动恢复
10009	你的应用回调接口出现 HTTP 错误	你的应用返回 ≥ 400	你的应用接口抛 5xx 或鉴权 4xx	看你的应用业务日志，按返回的 HTTP 状态定位	修复后自动恢复
10010	无效的正常 HTTP 状态码	你的应用返回非 200	你的应用返回 201/202/3xx 等，被识别为非正常	改成 200 返回正常 body	修复后自动恢复
10011	不是合法的 JSON 数据	—	你的应用接口返回非 JSON、JSON 字段缺失或类型不对	用文件元信息 schema 对照修复	修复后自动恢复
10012	File 数据不符合预期	—	缺少必填字段（如 `permissions.readable`）	对照文件模型逐字段补齐	修复后自动恢复
10013	FileType 数据不符合预期	—	`type` 字段不在枚举内	参考枚举与类型	修复后自动恢复
10014	User 数据不符合预期	—	用户接口缺 `id/name`，或字段类型不对	对照用户与组织模型修复	修复后自动恢复
10015	请求你的应用回调接口时发生网络错误	—	DNS 解析失败、连接拒绝、TLS 握手失败	检查 endpoint 域名 / 防火墙 / 公网可达；按需提供白名单 IP	网络恢复后自动重试

提示

首次接入或迁移环境时 1xxxx 高发，参考首次接入 SDK 报错应该排查哪些接口做最小回调集体检。

2xxxx 应用接口

发生在「调用方 → 石墨控制台/应用 API」这条链路。一般是参数错误或权限不足。

错误码	说明	常见 HTTP	修复动作	是否可重试
20001	创建应用参数错误	400	按返回 `message` 检查 name / endpointUrl / scope 等参数	改完参数再重新发起调用
20002	创建应用失败	500	偶现可忽略，重复出现联系石墨技术支持	短暂重试
20003	更新应用参数错误	400	按返回 `message` 检查	改完参数再重新发起调用
20004	更新应用失败	500	偶现可忽略，重复出现联系石墨技术支持	短暂重试
20005	应用不存在	404	检查 URL 路径里的 `appId`；确认应用未被删除	不可重试，请确认 ID

3xxxx 账号接口

发生在「调用方 → 接入账号 API」这条链路。

错误码	说明	常见 HTTP	修复动作	是否可重试
30001	创建接入账号参数错误	400	按返回 `message` 检查字段	改完参数再重新发起调用
30002	创建接入账号失败	500	偶现可忽略，重复出现联系石墨	短暂重试
30003	登录参数错误	400	检查账号、签名结构	改完参数再重新发起调用
30004	登录验证失败	401	偶现可忽略，重复出现联系石墨	短暂重试
30005	生成 Token 失败	500	偶现可忽略，重复出现联系石墨	短暂重试
30006	账号密码不匹配	401	检查账号 / 密码输入；注意首尾空白字符	修正后再试
30007	修改密码参数错误	400	按返回 `message` 检查字段	改完参数再重新发起调用
30008	修改密码失败	500	偶现可忽略，重复出现联系石墨	短暂重试

7xxxx 协同文档副本任务

发生在「调用方 → 创建协同文档副本」这条链路。由于副本是异步任务，调用方需要轮询同一个接口拿任务状态。下表里的 code 是接口在 200/400/500 响应 body 中返回的字段。

错误码	说明	出现 HTTP	修复动作	是否可重试
70015	获取源文件内容遇到错误	500	检查源文件 `fileId` 是否仍存在、可读	可短暂重试，如持续失败需人工介入
70016	目标文件存在但找不到副本任务信息	400	副本任务记录被清理或未创建；用新的目标 `fileId` 重新发起	不可在原 ID 上重试
70017	副本任务执行失败	400	看石墨侧日志（`requestId`）；常见为源文件损坏或权限丢失	排查后用新 ID 重试
70018	获取副本任务时遇到错误	500	偶现可忽略，重复出现联系石墨	短暂重试
70019	副本任务进行中	200	这不是错误，是「任务进行中」的提示，按轮询节奏继续请求	必须重试，按业务定的间隔轮询
70020	未知的副本任务状态	500	联系石墨技术支持，提供 `requestId`	短暂重试

9xxxx 预览相关

发生在「预览任务」链路。预览失败时，错误码会附在任务状态查询接口返回的 body 里。

错误码	说明	修复动作
90033	不支持的预览类型	文件类型不在支持范围；先用业务系统转码再预览
90035	下载源文件失败	检查 `downloadUrl` 是否公网可达、是否返回 200、是否设置 `Content-Type`
90042	文件带密码	提示用户解除密码或在业务侧先解密
90050 / 90052	文件过大	提示用户拆分文件，或联系石墨调整租户配额

12xxxx 导入 / 导出

错误码	说明	修复动作
120016	文件不支持导入	按支持的导入格式校验文件
120502 / 120507	单元格数量或单 sheet 行列数超限	拆分电子表格再导入
120509	文件过大	拆分文件或联系石墨调整配额

如果还遇到下表之外的 12xxxx 错误，请把 requestId 提交给石墨技术支持。

如何快速定位错误码#

错误码区间总览#

错误响应格式#

排查清单#

需要关注的字段#

错误码详细表#

1xxxx 你的应用回调对接#

2xxxx 应用接口#

3xxxx 账号接口#

7xxxx 协同文档副本任务#

9xxxx 预览相关#

12xxxx 导入 / 导出#

如何快速定位错误码

错误码区间总览

错误响应格式

排查清单

需要关注的字段

错误码详细表

1xxxx 你的应用回调对接

2xxxx 应用接口

3xxxx 账号接口

7xxxx 协同文档副本任务

9xxxx 预览相关

12xxxx 导入 / 导出