跳转到内容

错误与约定

组织操作使用 /api/v1/org,End User 操作使用 /api/v1/user,票据兑换使用 /api/v1/drive-downloads/{ticket} 或 /api/v1/drive-uploads/{ticket}。资源 ID、命令身份、token、游标和 ETag 都是不透明值。目标 ID 选择资源,不授予权限。

已提供字段规范的操作使用标准错误封装:

{ "error": { "code": "authentication_required", "message": "Authentication required" } }

可能附带 details。按操作约定的状态和稳定 code 判断,不解析人类可读 message。authentication_required 需要有效凭据;validation_error 需要修正请求;precondition_failed 需要先读取当前状态,再有意准备新编辑。

使用 x-request-id 关联请求,它是不透明值,与业务命令身份分开。

保存原命令身份及准确内容。通过原 interaction 回执恢复 Session 命令,单独读取执行历史。新身份可以授权新工作;连接关闭不是取消命令。

Drive 上传与文件写入各有其重试规则。外部写入或删除结果未知时先核对,不自动再次提交。

用户创建通过组织的 externalId 映射恢复,Key 签发通过元信息核对。丢失 Key 明文后需显式轮换。详见认证。

遵循每个集合的响应规范。hasMore 为 true 时,使用 nextCursor 和原范围、筛选条件继续读取。部分集合返回普通封装,分页按操作分别约定。

需要 If-Match 的编辑保留准确、带引号的 ETag。历史命令回执不是资源当前状态,也不是新 ETag。API 参考提供可用字段与请求头规范。