错误码说明

更新时间：2026-11-13

错误码

本文说明 DuMate Agent API 的错误响应结构、HTTP 状态码含义、限流规则，以及各接口的常见报错。

错误响应结构

HTTP 状态码大于等于 400 时，响应体统一为以下结构：

                JSON
                
            

                {
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "missing Authorization header"
  },
  "request_id": "req_5s3m53nfsxv7lbmanrm2ulul"
}
            

参数名称	类型	描述
`type`	String	固定为 `error`。
`error.type`	String	错误类型，与 HTTP 状态码对应，取值见下一节。
`error.message`	String	错误描述，可直接展示给开发者。
`request_id`	String	本次请求的唯一标识，与响应头 `request-id` 相同。反馈问题时请提供该值。

HTTP 状态码

HTTP 状态	error.type	含义	处理建议
400	`invalid_request_error`	参数不合法，或使用了暂不支持的能力	按 `message` 修正请求，不要重试
401	`authentication_error`	API Key 缺失或无效	检查请求头中的 API Key
402	`billing_error`	账号额度或计费异常	联系管理员
403	`permission_error`	无权访问该资源，例如会话不属于当前账号	检查资源归属
404	`not_found_error`	资源不存在	检查标识是否正确
409	`conflict_error`	状态冲突，例如版本号不匹配、资源已挂载、主线程不可归档	按 `message` 处理后重试
413	`request_too_large`	请求体过大	缩小请求体或文件
429	`rate_limit_error`	触发限流	按响应头 `Retry-After` 等待后重试
500	`api_error`	服务内部错误	带 `request_id` 反馈
502	`api_error`	上游异常	带 `request_id` 反馈，可重试
504	`timeout_error`	上游超时	稍后重试
529	`overloaded_error`	服务过载	退避后重试

其他 4xx 映射为 invalid_request_error，其他 5xx 映射为 api_error。

限流

每个接口有一条独立的限流规则，按 API Key 计数，不同 Key 互不影响。

阈值：每个接口每个 Key 每秒 100 次，按 1 秒固定窗口统计。
超限返回 429 rate_limit_error，message 为 request quota exceeded。

触发限流时额外返回以下响应头：

头域名称	说明
`X-RateLimit-Rule`	命中的限流规则标识。
`X-RateLimit-Limit`	窗口阈值。
`X-RateLimit-Remaining`	窗口内剩余可用次数。
`Retry-After`	建议等待的秒数，向上取整。

收到 429 后请按 Retry-After 等待再重试。

事件流中的错误

订阅会话事件流、线程事件流接口已返回 200 并开始推送后，后续错误不再改变 HTTP 状态码，而是以事件形式推送。

运行期错误推送 session.error 事件，error.type 的取值见「会话管理 / 获取会话事件历史」。

连接被关闭时推送 global.disposed 事件，reason 中包含上游的错误信息。例如 Last-Event-ID 传入不存在的事件标识：

Text

1event: global.disposed
2data: {"reason":"sse upstream status 409: {\"error\":{\"type\":\"conflict_error\",\"message\":\"Last-Event-ID is not present in this view\"}}"}

Last-Event-ID 格式不正确时，reason 中为 sse upstream status 400 与 Invalid Last-Event-ID。

常见错误速查

按资源分组列出各接口的常见报错。排查时建议以 HTTP 状态码和 error.type 为判断依据，message 仅用于定位具体原因。

认证与通用

HTTP	message	触发条件
401	`missing Authorization header`	未传 `Authorization` 或 `x-api-key`
401	`invalid API key`	API Key 无效
400	`limit must be between 1 and 100`	智能体、环境、会话、凭证空间、凭证列表的 `limit` 超出范围
400	`limit must be an integer between 1 and 1000`	文件、技能、技能版本列表的 `limit` 超出范围
400	`invalid page token`	翻页游标无效

分页上限按资源不同：智能体、环境、会话、凭证相关接口为 1–100，文件、技能、线程相关接口为 1–1000。

智能体

HTTP	message	触发条件
404	`agent agt_xxx not found`	智能体不存在
400	`tools[0].name must be at most 64 characters`	自定义工具名超过 64 字符
400	`tools[0].type "xxx" is not supported`	工具集类型不存在
400	`tools[0].configs[0].name "xxx" is not a valid built-in tool`	内置工具名不在 bash、edit、read、write、glob、grep、web_fetch、web_search 之内
400	`tools[0].default_config.permission_policy.type "auto" is not supported`	权限策略只支持 always_allow、always_ask
400	`tools[0].configs[0].allowed_domains is not supported for web_search`	域名限制仅 web_fetch 支持
400	`skills.version must be a string`	技能版本传了整数，应传技能接口返回的版本标识
400	`execution_identity.type "xxx" is not supported`	执行身份只支持 `service_account`
400	`multiagent is not supported`	多智能体编排配置当前未开放

环境

HTTP	message	触发条件
404	`environment env_xxx not found`	环境不存在
400	`config.type "self_hosted" is not supported, only "cloud" is allowed`	环境类型只支持 cloud
400	`config.packages.apt is not supported, only pip/npm are supported`	预装软件包只支持 pip、npm

会话与会话资源

HTTP	message	触发条件
404	`session ses_xxx not found`	会话不存在
400	`environment_id is required`	创建会话未传环境标识
404	`agent agt_xxx not found`	创建会话时智能体不存在
400	`budget.max_list_cost.currency "USD" is not supported, only "POINT"`	费用上限货币只支持 POINT
400	`vault_ids[0] vault_xxx is archived`	绑定了已归档的凭证空间
400	`该能力暂不支持：initial_events[0].type=user.define_outcome`	初始事件只支持 `user.message`
400	`该能力暂不支持：resources[0].type=github_repository`	会话资源只支持 `file`
400	`type "memory_store" is not supported`	挂载会话资源时类型不支持
404	`file node_xxx not found`	挂载的文件不存在
409	`resources file_id "node_xxx" is already mounted`	同一文件重复挂载到同一会话
404	`resource sesrsc_xxx not found`	会话资源不存在

会话事件

HTTP	message	触发条件
400	`events must not be empty`	`events` 为空或缺失
400	`events[0]: content must not be empty`	`user.message` 没有内容块
400	`该能力暂不支持：events[0].type=system.message`	事件类型不支持，`user.tool_result`、`user.define_outcome` 同样返回该格式
400	`该能力暂不支持：events[0].content[1].type=tool_use`	内容块类型不支持
400	`该能力暂不支持：events[0].content[0].source.type=url`	不支持服务端拉取外部 URL
400	`该能力暂不支持：events[0].content[0].source.media_type=image/bmp`	图片只支持 png、jpeg、gif、webp
400	`events[0]: result must be allow or deny`	工具确认的 `result` 取值错误
400	`Tool use does not exist`	`tool_use_id` 不存在
404	`Tool use does not exist`	`custom_tool_use_id` 不存在

工具确认与自定义工具回填的标识不存在时，HTTP 状态码不同：user.tool_confirmation 返回 400，user.custom_tool_result 返回 404。

文件

HTTP	message	触发条件
404	`file node_xxx not found`	上传文件不存在
404	`No artifact for this id`	会话产物不存在
400	`expires_in_seconds must be between 3600 and 7776000`	文件有效期超出范围
400	`scope_id is required to address an artifact file (file_id starts with "art_")`	访问会话产物未传 `scope_id`
400	`scope_id is only supported for artifact files (file_id must start with "art_")`	访问上传文件时传了 `scope_id`
400	`ids cannot be combined with page or limit`	`ids[]` 与 `page`、`limit` 同时使用
400	`artifact files cannot be deleted: engine does not support deleting artifacts`	尝试删除会话产物
404	`session ses_xxx not found`	按 `scope_id` 列文件时会话不存在

凭证空间与凭证

HTTP	message	触发条件
404	`vault vault_xxx not found`	凭证空间不存在
404	`credential cred_xxx not found`	凭证不存在
400	`display_name is required`	创建凭证空间未传显示名称
400	`auth is required`	创建凭证未传认证配置
400	`auth.networking is required`	`environment_variable` 类型未传网络策略
400	`auth.networking.type "limited" is not supported`	网络策略只支持 `unrestricted`
400	`auth.refresh.token_endpoint_auth must be an object`	该字段需传对象，不是字符串
400	`auth.mcp_server_url probe failed: MCP server is unreachable or rejected the credential`	创建 `mcp_oauth`、`static_bearer` 凭证时探测 MCP 服务失败
400	`auth.type cannot be changed from "environment_variable" to "static_bearer"`	更新凭证时修改了认证类型
409	`credential with secret_name "XXX" already exists in vault vault_xxx`	同一凭证空间内环境变量名重复
400	`credential cred_xxx is not an mcp_oauth credential`	对非 `mcp_oauth` 凭证调用校验接口

技能

HTTP	message	触发条件
404	`skill not found`	技能不存在
404	`skill version not found`	技能版本不存在
400	`files[] is required`	创建技能未上传文件
400	`SKILL.md is required at the root of the top-level directory`	上传文件中缺少顶层目录下的 `SKILL.md`
400	`source must be one of: custom, official`	技能列表的 `source` 取值错误
400	`version must be a version id; 'latest' is not supported here`	下载、删除技能版本时传了 `latest`

获取技能版本详情支持传 latest，下载版本内容和删除版本只接受具体的版本标识。

线程

HTTP	message	触发条件
404	`Session \`ses_xxx` not found.`	会话不存在
404	`Managed thread mapping does not exist`	查询线程详情时线程不存在
404	`Managed thread does not exist`	归档线程时线程不存在
409	`Archive the session to archive its primary thread`	尝试归档主线程，应改为归档整个会话
400	`Invalid thread list filter`	线程列表参数不合法，例如 `limit` 超出范围
400	`Invalid event query or cursor`	线程事件历史参数或游标不合法

评价此篇文章

有帮助没帮助

线程管理

API参考（旧）

百度智能云

百度搭子