错误响应
HTTP 状态码按错误码一级前缀映射，只作粗粒度分类，判定请以
code 为准（例如 FailedOperation.* 是业务失败，HTTP 层是 500）：HTTP | 一级错误码前缀 | 典型场景 |
400 | InvalidParameter / InvalidParameterValue / MissingParameter / UnknownParameter / InvalidFilter / InvalidParameterCombination | 参数缺失、格式错误、取值非法 |
401 | AuthFailure | 凭据缺失 / 无效 / 过期，或调用方身份无法解析 |
403 | UnauthorizedOperation / OperationDenied / UnsupportedOperation | 已认证但无权操作：企业不匹配、服务未开通、数据范围拒绝 |
404 | ResourceNotFound | Agent / 版本 / 会话 / 外部 Agent 不存在 |
409 | ResourceInUse | 资源冲突（如 Agent 重名） |
429 | LimitExceeded / RequestLimitExceeded / ResourcesSoldOut / ResourceInsufficient | 超过限频或配额 |
503 | ResourceUnavailable | 依赖未就绪（如 A2A 网关未配置） |
500 | InternalError / FailedOperation / 其他 | 服务内部或下游失败 |
网关层错误由 APISIX 直接返回，不带业务
code：凭据缺失或无效 → 401；凭据所属企业与路径 {enterpriseId} 不一致 → 403；单 IP 超过限频阈值（默认 600 次/秒）→ 429。公共错误码
下列错误码由分发器 / 中间件统一返回，所有接口都可能出现，各接口的错误码表不再重复列出：
错误码 | 说明 |
AuthFailure.IdentityNotFound | 未找到与当前 Uin / SubAccountUin 对应的用户身份 |
FailedOperation.EntitlementNotFound | 未查询到服务开通记录，请先开通服务 |
InternalError.EntitlementCheckFailed | 服务开通状态校验失败 |
InternalError.MarshalFailed | 响应序列化失败 |
InternalError.Panic | 处理过程中发生 panic，已被恢复 |
InternalError.ReadBodyFailed | 读取请求体失败 |
InternalError.Unknown | 内部错误 |
InvalidParameter.ActionNotFound | 未找到对应的 Action |
InvalidParameter.ActionRequired | 缺少 Action 参数 |
InvalidParameter.EmptyBody | 请求体为空 |
InvalidParameter.InvalidJSON | 请求体不是合法 JSON |
InvalidParameter.QueryParameter | 查询参数取值与声明类型不符 |
MissingParameter.UinRequired | 公共参数中缺少 Uin |
UnauthorizedOperation.PermissionDenied | 调用方缺少该接口所需的权限 |
各接口自身的业务错误码见对应接口的“错误码”表。
