所有接口统一返回 ApiResponseEnvelope:{ code, message, request_id, data? }。成功时 code=0、message="ok";业务错误时 code 非0,且 data 字段通常缺省。调用方应以 code 为唯一判定准绳,不要依赖 HTTP 状态码。
HTTP 状态码由 code 推导:code=0 → 200;code 在400 – 599区间 → 与该值同值的 HTTP 状态码;其他业务码(如4291)→ HTTP 200。
request_id 优先取上游 x-request-id 或 x-qcloud-transaction-id 头,否则由服务端生成 req-<16位 hex>。5xx 与未捕获异常路径的响应体还会额外带 trace_id、retryable 字段(部分遗留路径还保留 error 字段),联系技术支持时请携带 request_id。
错误码列表
错误码 | 含义 | 触发场景 | 处理建议 |
0 | 成功 | 接口正常处理。 | — |
400 | 请求参数非法 | 必填参数缺失、取值不合法、数组超长等 Zod 校验失败。例如 POST /v3/atomic/delete 的 ids 缺省或为空数组;POST /v3/conversation/delete 的 message_ids、session_ids、session_id 全部缺省(三者至少提供一个,可同时提供);字段超长:content 上限8192字符,query 上限2048字符;批量删除超上限:message_ids 5000条、session_ids 100条、ids 5000条 | 按各接口请求参数说明检查字段类型、必填性、长度与数量上限 |
401 | 鉴权失败 | Authorization 头缺失或不是 Bearer <API Key> 格式;x-tdai-service-id 头缺失;API Key 无效 | 检查 Authorization: Bearer <API Key> 与 x-tdai-service-id: <Service_ID> 两个头 |
403 | 无操作权限 | 资源存在,但不属于当前调用上下文。例如 POST /v3/atomic/update 的目标记录 user_id / agent_id 与调用上下文不一致;元数据接口传入的 team_id 与资源实际归属不符 | 确认资源由当前租户 / Agent 创建,或改用具备权限的凭证 |
404 | 资源不存在或无权访问 | 目标 id / path 在存储中不存在。例如 POST /v3/atomic/update 指定的原子记忆 id 不存在;POST /v3/scenario/write 指定的 path 不存在(该接口不创建新文件);POST /v3/core/read 无画像时不返回404,而是 200+ 空内容 | 确认 id / path 是否正确、是否已生成 |
413 | 请求体过大 | 整个 HTTP 请求体字节数超过服务端上限(不是单字段字符数超限,单字段超限走400);Skill 包资源总大小 > 5MB 或单文件 > 1 MB 时也按413拒绝(业务码41301) | 压缩或拆分请求体,裁剪 Skill 资源; content / query 长度限制请参考 400 说明 |
429 | 记忆配额超限 | 累计记忆条数超过当前 Service 的配额(注意:这是条数配额,不是调用频率限流) | 清理无用记忆释放配额,或申请提升配额 |
500 | 服务内部错误 | 服务端未预期的异常。 | 携带 request_id 联系技术支持排查。 |
归属校验契约
403与404可区分:资源不存在返回404;资源存在但不属于当前上下文返回403。服务端不会把"存在但无权访问"伪造成404。
批量删除静默跳过:POST /v3/conversation/delete、POST /v3/atomic/delete 中,不存在或不属于当前上下文的 id 会被静默跳过,不计入 deleted_count,也不报错,接口仍返回 code=0。
错误响应示例
错误响应同样遵循
ApiResponseEnvelope 结构:{"code": 400,"message": "At least one of message_ids or session_ids must be provided","request_id": "req-7fd3b2dd3f1a4c28"}
{"code": 404,"message": "Atomic note not found: atom-123","request_id": "req-7fd3b2dd3f1a4c28"}
说明:
业务错误时
data 字段可能缺省,调用方需以 code 字段为判定准绳;遇到非预期错误时,建议携带 request_id 联系技术支持以便快速定位。