帮你快速理解、总结文档立即下载

错误码

最近更新时间:2026-11-06 17:40:30
我的收藏
所有接口统一返回 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 联系技术支持以便快速定位。