# 错误码与异常状态参考

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

## MOI / AI Studio HTTP API 错误信封

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

```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 发送，详见[调用失败时的检查](../developer/quickstart/ai-studio/http-api.md#调用失败时的检查) |
| `400` | `ErrWorkspaceRequired` | 请求缺少目标工作区标识 | 在请求头中传入合法的 `X-Workspace-ID` |
| `401` | `ErrUnauthorized`、`ErrUnauthenticated`、`Unauthorized`、`unauthenticated` | 认证凭据缺失、已过期、被停用，或误将 AI Studio 个人访问令牌放入 `Authorization: Bearer` | 调用 AI Studio 数据/管理接口时改用 `X-API-Key` 传入个人访问令牌；终端令牌过期请重新获取 |
| `403` | `ErrForbidden` | 当前账号缺少该工作区操作角色、平台管理员身份，或浏览器会话请求缺少有效 CSRF Token | 联系工作区管理员核对[角色权限](../guides/ai-studio/permissions/roles.md)；管理员接口须使用已配置的管理员身份 |
| `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` | 服务端内部未预期异常 | 记录请求时间、请求路径与返回原文，联系[技术支持](../get-started/support.md) |
| `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`：

```json
{
  "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](../guides/billing/manage-billing.md)充值后重试 |
| `404` | `model_not_found` | 模型 ID 不正确、尚未启用，或不在当前租户/套餐允许的模型列表中，详见[查看模型列表](api/genesis/models.md) |
| `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 选项与实例要求一致（见[数据库实例](../guides/matrixone/instances.md)）。
- **用户认证或越权报错**：确认登录格式（含 `用户名:角色名` 形式），核对对象级 `GRANT` 权限与租户隔离规则（见[MatrixOne 权限](../guides/matrixone/permissions.md)与[权限分类](sql/privileges.md)）。
- **语法或导入限制**：查看[使用限制](sql/limitations.md)及 [SQL 编辑器](../guides/ai-studio/processing/sql-editor.md) 说明。

## 延伸阅读

- 按症状自检控制台、入库、计算资源与沙箱问题：[常见问题与故障排查](../get-started/troubleshooting.md)
- 统一调用地址、认证头区分与工作区 ID 获取：[调用前准备](api/common/index.md)
- 需要提交工单排查并附带诊断标识：[技术支持与反馈](../get-started/support.md)
