错误码说明

全产品错误参考 + 调试流程。Agent 遇到错误时查阅此文档。

错误返回格式

{"success": false, "code": "InvalidParameter", "message": "baseId is required"}
{"success": false, "code": "AUTH_TOKEN_EXPIRED", "message": "Token验证失败"}
{"success": false, "code": "PermissionDenied", "message": "无权限访问该资源"}

错误分类与 Agent 行为

可自行修复

参数缺失 / 格式错误 / ID 无效 → 检查参数后修正重试

需用户介入

权限不足 / 资源不存在 / 配额超限 → 报告完整错误信息给用户，不要自行尝试替代方案

通用错误

请求超时 — 网络慢或服务端响应慢 → --timeout 60 重试
网络连接失败 — 无法连接 MCP Server → 用最简命令验证: dws contact user get-self --format json
stderr 出现 RECOVERY_EVENT_ID=<event_id> — runtime 失败已被 CLI 捕获 → 优先执行 dws recovery execute --event-id <event_id> --format json

Recovery 闭环

dws recovery plan --last|--event-id <event_id> --format json：读取失败快照并生成恢复计划
dws recovery execute --last|--event-id <event_id> --format json：生成带 doc_search、probe_results、agent_task 的分析包
dws recovery finalize --event-id <event_id> --outcome recovered|failed|handoff --execution-file execution.json --format json：回写恢复结果

执行 finalize 时：

execution-file 至少应包含 actions、attempts、result、error_summary
兼容旧格式：action + 数值型 attempts
若 recovery bundle 已进入 unknown/agent 路线，不要把 human_actions 视为最终结论；必须结合完整 bundle 判断

更多字段解释见 recovery-guide.md。

aitable 高频错误

参数体系: baseId / tableId / fieldId / recordId。CLI flag 用 kebab-case（--base-id），JSON 内用 camelCase（baseId）。

参数缺失 / 无效请求 — 还在用旧参数 dentryUuid / --doc / --sheet → 改用 --base-id / --table-id / --field-id / --record-ids
参数传了但服务端没收到 — flag 用了 camelCase（如 --baseId）→ flag 用 kebab-case: --base-id <ID>
record query --filters 无结果 — 单选/多选过滤用了 option name 而非 id → 先 field get 读取 options，用 option id 过滤
record create/update 失败 — cells key 用了字段名（应为 fieldId）；特殊字段格式错误 → 先 table get 拿字段目录；url 传 {"text":"..","link":".."}
更新选项后历史数据异常 — 更新 options 没传完整列表 / 没保留原 id → 先 field get 取完整配置，保留已有 option 的 id
cannot delete the last table — 该表是 Base 最后一张表 → 先新建表再删旧表，或用 base delete
formula 类型 not supported yet — 部分字段类型暂不支持 API 创建 → 复杂字段拆开单独创建，先建基础结构

排查链路: base list → base get(→tableId) → table get(→fieldId) → record query(→recordId)。别跳步，别猜 ID。

批量上限: record 100 条 / field 15 个 / table·field 详情 10 个。

approval 高频错误

approve/reject 缺少 taskId — 未先获取审批任务 → 先 approval tasks --instance-id <ID> 获取 taskId
list-initiated 缺少 processCode — 未查询审批表单 → 先 approval list-forms 获取 processCode
撤销审批失败 — 非本人发起的审批 → revoke 只能撤销自己发起的审批

chat 高频错误

参数互斥报错 — --group 与 --users 同时传入 → 群聊用 --group，单聊用 --users，二者互斥
群不存在 — openConversationId 不正确 → chat search --query "群名" 获取正确 ID
机器人无法添加到群 — 当前用户非群管理员 → 报告给用户，需群管理员操作
Webhook Token 无效 — token 不正确或已失效 → 确认 Webhook Token 来源正确
添加/移除群成员失败 — userId 不正确或无权限 → 先 contact user search 确认 userId，需当前用户为群管理员

calendar 高频错误

时间格式错误 — 未使用 ISO-8601 格式 → 标准格式: 2026-03-10T14:00:00+08:00
会议室搜索报错 / 返空 — 企业会议室超 100 条未分组查询 → 先 room list-groups → 按 --group-id 逐组搜索
参与者 / 会议室添加失败 — eventId 不正确 → 先 event list 或 event create 获取正确 eventId

contact 高频错误

dept list-children 报错 — --id 传了非整数值 → deptId 必须为整数，从 dept search 获取

通用排查三步法

确认 ID — 从最顶层资源逐级获取，不猜 ID、不跳步
确认参数 — flag 用 kebab-case，JSON 用 camelCase；特殊字段查产品参考文档确认格式
确认限制 — 检查批量上限和已知约束（各产品注意事项见对应产品参考文档）

4.9 KiB Raw Blame History Unescape Escape