错误码与异常状态参考

本页汇总 MatrixOne Intelligence(MOI)REST API、Genesis 模型网关、沙箱运行时与 MatrixOne 数据库常见错误码、HTTP 状态码与对应处理方向。具体接口专属错误请结合对应 API 参考动作页核对;高频控制台与接入问题排查见常见问题与故障排查。

MOI / AI Studio HTTP API 错误信封

AI Studio 平台与管理接口在失败时返回标准 JSON 错误结构(具体字段以接口动作页为准):

{
  "code": "ErrParamInvalid",
  "msg": "readable localized message"
}

通用 HTTP 与业务错误码

HTTP 状态码

常见 code

含义与常见触发原因

处理建议

400

ErrParamInvalid

请求参数缺失、字段格式不合法、JSON 体无法解析或存在未知字段

检查请求体大小(常规上限 1 MiB)、必填字段和参数格式

400

ErrMultipleAuthCredentials

同一请求同时传递了多种认证凭据(例如同时传 X-API-Key 与 Authorization: Bearer,或客户端自动附带了产品会话 Cookie)

保持单一认证方式;使用专有 API 客户端并清理或禁用请求路径的 Cookie 发送,详见调用失败时的检查

400

ErrWorkspaceRequired

请求缺少目标工作区标识

在请求头中传入合法的 X-Workspace-ID

401

ErrUnauthorized、ErrUnauthenticated、Unauthorized、unauthenticated

认证凭据缺失、已过期、被停用,或误将 AI Studio 个人访问令牌放入 Authorization: Bearer

调用 AI Studio 数据/管理接口时改用 X-API-Key 传入个人访问令牌;终端令牌过期请重新获取

403

ErrForbidden

当前账号缺少该工作区操作角色、平台管理员身份,或浏览器会话请求缺少有效 CSRF Token

联系工作区管理员核对角色权限;管理员接口须使用已配置的管理员身份

404

ErrNotFound

目标对象 ID 不存在、已删除,或不在当前工作区可见范围内

确认 X-Workspace-ID 与目标资源 ID 是否一致

409

ErrAlreadyExists、ErrDuplicateName、ErrDuplicateKey、ErrConflict

名称或键已存在、工作流或任务处于不可变更状态、资源被下游绑定占用(含 workflow_rerun_conflict、rerun_contract_mismatch、api_service_disabled)

更换唯一名称,或先停止/解除依赖后再执行删除或状态变更

429

ErrDynamicServiceConcurrencyLimit、ErrDynamicServiceRateLimit

动态算子服务或工作流发布服务并发数 / 请求频率达到上限

降低并发度并实施指数退避重试

500

ErrServer

服务端内部未预期异常

记录请求时间、请求路径与返回原文,联系技术支持

503 / 502

ErrServiceUnavailable

权限判定、账户偏好或上游基础设施暂时不可用

稍后退避重试;若持续报错请确认上游服务状态

沙箱与运行环境专属错误码

HTTP 状态码

错误码 code

含义与处理方向

400

SANDBOX_INVALID_NAME、SANDBOX_INVALID_SPEC

沙箱名称不合规,或规格 / 磁盘设置超出环境支持范围

400

SANDBOX_EGRESS_INVALID_HOST、SANDBOX_EGRESS_MISSING_PORT、SANDBOX_EGRESS_INVALID_PORT、SANDBOX_EGRESS_HOST_LIMIT_EXCEEDED、SANDBOX_EGRESS_PORT_LIMIT_EXCEEDED

出网白名单端点未按 域名:端口 格式填写,或超过域名 / 端口数量限制

400

SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE、SANDBOX_NETWORK_UNRESTRICTED_DISABLED

当前部署未开放白名单配置或禁止无限制出网模式

403

SANDBOX_FORBIDDEN

无权访问或修改该托管沙箱(含管理员操作权限不足)

404

SANDBOX_NOT_FOUND、SANDBOX_COMPUTE_RESOURCE_NOT_FOUND

托管沙箱或目标关联计算资源不存在

409

SANDBOX_QUOTA_EXCEEDED

工作区托管沙箱或临时沙箱数量达到配额上限;请清理闲置托管环境或联系管理员调整工作区配额

409

SANDBOX_COMPUTE_RESOURCE_NOT_BINDABLE、SANDBOX_WORKSPACE_DELETING、SANDBOX_REQUEST_CONFLICT、SANDBOX_MANUAL_RECOVERY_REQUIRED

所选计算资源不支持绑定、工作区处于删除中,或环境处于需管理员/人工介入清理的冲突态

409

SESSION_WORKSPACE_CONFLICT、SESSION_WORKSPACE_NOT_SAVED、SESSION_WORKSPACE_RECOVERY_INCOMPLETE

会话关联工作区状态未保存或恢复未完成,请按提示完成保存或等待状态收敛后再新建会话环境

503

SANDBOX_IAM_UNAVAILABLE、SANDBOX_CREDENTIAL_UNAVAILABLE、SANDBOX_NETWORK_STORAGE_UNAVAILABLE

沙箱依赖的鉴权、凭据或网络存储组件暂不可用,稍后重试

500

SANDBOX_ERROR

未分类沙箱运行或 Provider 异常,请保存环境 ID 与报错时间排查或提交工单

Genesis 模型网关与服务账号错误

Genesis 数据面接口采用 OpenAI 兼容错误格式,响应中包含便于定位的 request_id:

{
  "error": {
    "message": "insufficient credit",
    "type": "billing_error",
    "param": "",
    "code": "insufficient_credit",
    "request_id": "..."
  }
}

HTTP 状态码

常见 error.code

含义与处理建议

400

invalid_request、provider_schema_error、context_length_exceeded

请求参数值不合法(参见 error.param)、请求结构与目标模型协议不匹配,或输入 Token 超过模型上下文窗口;请精简上下文或更换长上下文模型

401 / 403

invalid_api_key、authentication_error、permission_error

凭据缺失、已过期/停用,或服务账号不具备该模型的执行权限;Genesis 须使用 Authorization: Bearer <sk-uca-v1 | sk-sa-v1 | sk-mo>,不可使用 Cookie 或管理 JWT

402

insufficient_credit

账户可用 Credit 不足;请前往充值 Credit充值后重试

404

model_not_found

模型 ID 不正确、尚未启用,或不在当前租户/套餐允许的模型列表中,详见查看模型列表

413

request_body_too_large

单次 HTTP 请求体字节数超出模型网关上限,请拆分文件或缩减请求载荷

429

rate_limit_exceeded、all_providers_rate_limited

触发 API Key、服务账号 RPM/TPM/并发上限,或上游全部渠道限流;读取响应头 Retry-After 并退避重试

502 / 503

upstream_error、account_rate_limits_unavailable

上游模型渠道全部调用失败,或限流策略读取服务暂不可用;保存 request_id 稍后重试或联系支持

MatrixOne 实例与 SQL 常见错误定位

直接连接或通过 AI Studio 操作 MatrixOne 数据库实例时,异常主要源于连接准入、租户权限或语句约束:

  • 连接失败或被拒绝:确认实例状态为运行中,核对公网/私网接入点与端口,检查实例**网络策略(允许指定 IP)**是否放行当前出口 IP,并确认 TLS/SSL 选项与实例要求一致(见数据库实例)。

  • 用户认证或越权报错:确认登录格式(含 用户名:角色名 形式),核对对象级 GRANT 权限与租户隔离规则(见MatrixOne 权限与权限分类)。

  • 语法或导入限制:查看使用限制及 SQL 编辑器 说明。

延伸阅读

最后更新于