错误码

本文介绍 DolphinX API 的错误码体系，方便开发者根据错误码在应用层提供更准确的提示或恢复策略。

1. 错误响应示例

{
 "type": "ERROR",
 "msgId": "...",
 "correlationId": "<requestId>",
 "action": "<action>",
 "agentId": "<agentId>",
 "sessionId": "<sessionId>",
 "error": {
 "code": "<BusErrorCode>",
 "message": "<错误描述>",
 "reason": "<业务原因，可选>",
 "providerStatus": "<LLM provider HTTP 状态码，可选>",
 "providerCode": "<LLM provider 错误码，可选>",
 "retryable": "<true|false，可选>"
 },
 "headers": {
 "busErrorCode": "<BusErrorCode>",
 "httpStatus": "<HTTP 状态码>",
 "llmProviderStatus": "<LLM provider HTTP 状态码，可选>",
 "providerCode": "<LLM provider 错误码，可选>",
 "retryable": "<true|false，可选>"
 }
}

2. 错误码说明


错误码	HTTP 状态码	说明
BUS_UNAUTHENTICATED	401	未认证或登录态失效，客户端应重新登录。
BUS_PERMISSION_DENIED	403	已认证但无权执行此操作，客户端不应清除登录态。
BUS_UNKNOWN_ACTION	404	未知的 action，请求的接口/action 名称不存在。
BUS_NOT_FOUND	404	通用资源不存在。
BUS_AGENT_NOT_FOUND	404	指定的 Agent 不存在或已被删除。
BUS_SESSION_NOT_FOUND	404	指定的会话不存在。
BUS_CONFLICT	409	资源状态冲突，例如重复创建、版本冲突或当前资源状态不允许执行该操作。
BUS_QUEUE_FULL	429	DolphinX API 请求队列已满，服务端过载，请稍后重试。
BUS_RATE_LIMITED	429	DolphinX 侧限流。
BUS_TIMEOUT	504	DolphinX 请求处理超时。
BUS_NODE_UNREACHABLE	503	集群模式下目标节点不可达，请求无法路由。
BUS_HANDLER_ERROR	500	处理器内部错误，详见错误响应中的 `error.message`。
BUS_LLM_PROVIDER_ERROR	502	上游 LLM 供应商返回 5xx、响应无法解析或没有有效 LLM 输出；供应商原始 HTTP 状态见错误响应中的 `error.providerStatus` 或 `headers.llmProviderStatus`。
BUS_LLM_CONFIG_ERROR	502	LLM 配置、供应商、鉴权密钥或模型不可用；供应商 401/403/404 错误归入此类。
BUS_LLM_QUOTA_EXCEEDED	402	LLM 账户余额或 token 额度不足。
BUS_LLM_RATE_LIMITED	429	LLM 供应商限流或返回 `too many requests`。
BUS_LLM_PROVIDER_TIMEOUT	504	LLM 请求超时或供应商返回 408/504。
BUS_CONTEXT_LENGTH_EXCEEDED	413	上下文窗口或 token 限制超出，包含本地上下文预算超出和 `provider context length` 错误。
BUS_STREAM_INTERRUPTED	499	流式传输中断（SSE 连接断开或 LLM 流式响应异常终止）。
BUS_INVALID_ARGUMENT	400	请求参数不合法（缺少必填字段、类型错误、值超出范围等）。
BUS_PAYLOAD_TOO_LARGE	413	请求体或 payload 超限。
REPLACE_REJECTED	409	`workspace.replace` 请求被拒绝，详见错误响应中的 `error.reason` 和 `error.message`。
WORKSPACE_REJECTED	400	Workspace 状态、文件或平台约束导致拒绝，详见错误响应中的 `error.reason` 和 `error.message`。
BUS_NOT_STARTED	503	DolphinX API 尚未完成初始化，服务暂不可用。

LLM 供应商错误响应通常会在 error 与 headers 中携带以下附加字段：


字段	说明
providerStatus / llmProviderStatus	LLM 供应商原始 HTTP 状态码。
providerCode	LLM 供应商原始错误码。能从响应中解析出来时才会返回。
retryable	是否可以重试。值为 "true" 或 "false"；`BUS_LLM_RATE_LIMITED`、`BUS_LLM_PROVIDER_TIMEOUT`、`BUS_LLM_PROVIDER_ERROR` 为可重试类别。

Workspace 业务错误的具体原因在错误响应的 error.reason 和 error.message 中通过标识体现。常见标识如下：


标识	说明
missing_hash	`replace` 请求缺少 hash。
stale_file	`replace` 请求 hash 与当前文件 hash 不一致。
invalid_replacements	replacement 缺失、为空或格式非法。
empty_old	replacements[].old 为空。
old_not_found	replacements[].old 不存在。
old_not_unique	`replaceAll=false` 时 old 出现多次。
invalid_text	文件内容或 replacement 文本不是 UTF-8。
file_not_found	Workspace 文件不存在。
quota_exceeded	Workspace 总大小、单文件大小或文件数量超过限制。
target_invalid	目标不是 Workspace 内的普通文件。