# 错误码

查看错误码、界面提示和处理方法。

界面提示与接口错误码使用同一份错误定义。可根据错误码查询 HTTP 状态、界面提示和处理方法。

## 开始前

- 界面排查：记下提示原文即可，用户不需要看到错误码。
- 接口排查：看响应体的 `code` 字段，配合 HTTP 状态定位。API-Key、CLI、MCP 调用都返回同样的结构。
- 拿到 trace id：对话页的「复制 trace id」能拷出本轮标识，提工单时带上它比截图有用。

## 关键约束

AskTable 的业务异常统一返回这个结构：

```json
{
  "code": "RESOURCE_QUOTA_EXCEEDED",
  "message": "Resource quota exceeded for datasources (50/50)",
  "params": { "resource_type": "datasources", "current_count": 50, "limit": 50 }
}
```

| 项目        | 值或默认                                                                             | 在哪里改 |
| --------- | -------------------------------------------------------------------------------- | ---- |
| 响应体字段     | `code`、`message`、`params`                                                        | —    |
| 界面提示来源    | 前端按 `code` 取本地化文案，不使用服务端 `message`                                               | —    |
| 追加的上下文    | 服务端给了自定义消息时，`params.detail` 会被拼成「本地化文案：detail」                                   | —    |
| 没有对应文案时   | 界面统一显示「操作失败，请稍后重试」                                                               | —    |
| 参数校验失败    | HTTP 422，`code` 固定是 `VALIDATION_ERROR`，`params.errors` 里是逐字段的 `loc`、`msg`、`type` | —    |
| 4xx 与 5xx | 4xx 是业务异常（不触发告警），5xx 会触发告警                                                       | —    |

## 出问题怎么判断

### 资源与配额

| 错误码                        | HTTP | 界面提示原文                     | 处理                      |
| -------------------------- | ---- | -------------------------- | ----------------------- |
| `RESOURCE_ERROR`           | 400  | 「资源操作失败」                   | 按提示补全或修正参数后重试           |
| `RESOURCE_NOT_FOUND`       | 404  | 「资源不存在」                    | 目标已被删除，刷新页面重新进入         |
| `RESOURCE_ALREADY_EXISTS`  | 409  | 「X名称已存在」                   | 换一个名称                   |
| `RESOURCE_QUOTA_EXCEEDED`  | 403  | 「X数量已达上限（N/M），请删除不需要的X后重试」 | 删掉不用的旧资源；项目资源配额只在云端部署执行 |
| `DATABASE_INTEGRITY_ERROR` | 409  | 「数据完整性冲突」                  | 先解除引用关系再重试              |

### 数据源与元数据

| 错误码                                  | HTTP | 界面提示原文                             | 处理                                                      |
| ------------------------------------ | ---- | ---------------------------------- | ------------------------------------------------------- |
| `ACCESSOR_ERROR`                     | 400  | 「数据库连接失败」                          | 核对连接信息，见[连接数据源](https://docs.asktable.com/data/connect) |
| `ACCESSOR_CONNECTION_ERROR`          | 400  | 「无法连接到数据库」                         | 核对地址、网络和账号；云端部署确认已加白名单                                  |
| `DATASOURCE_META_PROCESSING`         | 409  | 「数据源元数据正在处理中」                      | 等元数据解析完成                                                |
| `DATASOURCE_META_NOT_READY`          | 400  | 「数据源元数据未就绪」                        | 先完成元数据解析                                                |
| `DATASOURCE_CONFIG_ERROR`            | 400  | 「数据源配置错误」                          | 到数据源「设置」里检查配置                                           |
| `TABLE_REFRESH_ALREADY_RUNNING`      | 409  | 「另一次刷新正在进行中，请等其完成再试」               | 等本次刷新结束                                                 |
| `WORKBOOK_NAME_CONFLICT`             | 409  | 「数据源名称「X」已存在，换个名字试试」               | 换一个数据源名称                                                |
| `WORKBOOK_READ_ONLY`                 | 403  | 「飞书同步工作簿为只读，不能在 AskTable 内修改结构或数据」 | 改到飞书侧改                                                  |
| `WORKBOOK_FEISHU_SYNC_RUNNING`       | 409  | 「飞书同步正在进行中，请稍后再试」                  | 等同步结束                                                   |
| `WORKBOOK_FEISHU_SOURCE_NOT_FOUND`   | 404  | 「未找到飞书同步配置」                        | 重新建一次同步配置                                               |
| `WORKBOOK_FEISHU_CREDENTIAL_INVALID` | 422  | 「飞书应用凭证无效，请检查 App ID 和 App Secret」 | 重填凭证                                                    |
| `WORKBOOK_FEISHU_APP_TOKEN_INVALID`  | 422  | 「飞书多维表格 App Token 无效或无权访问」         | 确认该表对应用可见                                               |
| `WORKBOOK_FEISHU_INVALID_URL`        | 422  | 「链接无法识别为多维表格，请粘贴多维表格页面的完整 URL」     | 粘完整 URL 再试                                              |
| `WORKBOOK_FEISHU_TABLE_MISSING`      | 422  | 「飞书表 X 不存在或无权访问」                   | 重新选表                                                    |
| `WORKBOOK_FEISHU_NO_TABLE_SELECTED`  | 422  | 「请至少选择一个飞书表」                       | 至少勾一张表                                                  |

### 文件上传

| 错误码                         | HTTP | 界面提示原文                                         | 处理                           |
| --------------------------- | ---- | ---------------------------------------------- | ---------------------------- |
| `DATA_FILE_ERROR`           | 400  | 「文件处理出错」                                       | 重新上传；持续失败换一个文件试              |
| `FILE_METADATA_PARSE_ERROR` | 400  | 「解析字段 X 时出错」                                   | 检查该列的内容和格式                   |
| `TOO_MANY_SHEETS`           | 400  | 「Excel 文件包含过多工作表」                              | 拆成多个文件，或调大「Excel 最大 Sheet 数」 |
| `FILE_RETRIEVAL_FAILED`     | 400  | 「文件获取失败」                                       | 重新上传                         |
| `FILE_TOO_LARGE`            | 400  | 「文件大小超过 X MB 限制」                               | 调大对应的大小上限，或压缩、拆分文件           |
| `FILE_TYPE_NOT_SUPPORT`     | 400  | 「不支持 X 文件类型」                                   | 换成 `.xlsx`、`.xls`、`.csv`     |
| `FILE_FORMAT_ERROR`         | 400  | 「文件格式无效或无法识别，文件可能已损坏或被加密，请用 Excel 打开确认后另存为再上传」 | 用 Excel 另存为后再上传              |

### 认证与用户

| 错误码                         | HTTP | 界面提示原文        | 处理                                                  |
| --------------------------- | ---- | ------------- | --------------------------------------------------- |
| `AUTH_ERROR`                | 401  | 「认证失败」        | 重新登录                                                |
| `TOKEN_EXPIRED`             | 401  | 「登录已过期，请重新登录」 | 重新登录                                                |
| `TOKEN_INVALID`             | 401  | 「登录凭证无效」      | 重新登录；API 调用换一个新 key                                 |
| `INVALID_CREDENTIALS`       | 401  | 「邮箱或密码错误」     | 核对账号密码                                              |
| `PROVIDER_AUTH_FAILED`      | 401  | 「第三方登录失败」     | 见[企业身份登录](https://docs.asktable.com/admin/identity) |
| `PASSWORD_MISMATCH`         | 401  | 「原密码不正确」      | 重填原密码                                               |
| `USER_DISABLED`             | 403  | 「用户已被禁用」      | 找管理员在左侧「用户」里处理                                      |
| `VERIFICATION_CODE_INVALID` | 401  | 「验证码无效或已过期」   | 重新获取验证码                                             |

### 权限与语义层

| 错误码                                | HTTP | 界面提示原文                  | 处理                                                             |
| ---------------------------------- | ---- | ----------------------- | -------------------------------------------------------------- |
| `PERMISSION_DENIED`                | 403  | 「权限不足」                  | 补项目成员身份或数据范围，见[权限与数据安全](https://docs.asktable.com/permissions) |
| `SEMANTIC_WRITE_PERMISSION_DENIED` | 403  | 「无权编辑语义层，需要管理员权限」       | 由项目负责人或项目管理员操作                                                 |
| `SEMANTIC_WRITE_ROLE_CONFLICT`     | 400  | 「语义层写入不能与会话角色同时使用」      | 先取消会话角色再开启写入                                                   |
| `SEMANTIC_VALIDATION_FAILED`       | 400  | 「语义层校验失败，无法导出 dbt YAML」 | 按校验提示修正后再导出                                                    |
| `SEMANTIC_EXPORT_FAILED`           | 400  | 「dbt YAML 导出失败」         | 修正语义层后重试                                                       |
| `ROLE_IN_USE`                      | 409  | 「角色正被 N 个智能体白名单引用，无法删除」 | 先从相关智能体的白名单里移除该角色                                              |

### 对话与查询

| 错误码                             | HTTP | 界面提示原文                            | 处理                                                            |
| ------------------------------- | ---- | --------------------------------- | ------------------------------------------------------------- |
| `CHAT_ERROR`                    | 400  | 「对话出错」                            | 重发一次；持续失败带上 trace id 提工单                                      |
| `NO_DATA_TO_QUERY`              | 400  | 「没有可查询的数据表或字段」                    | 确认数据源已接入并选过表                                                  |
| `CANNOT_HANDLE`                 | 400  | 「查询过于复杂，请简化后重试」                   | 拆成几步问                                                         |
| `SQL_UNKNOWN_TABLE`             | 400  | 「数据源中找不到表 X（schema Y）」            | 到数据源详情页重新选表                                                   |
| `SQL_UNKNOWN_FIELD`             | 400  | 「表 X 上找不到字段 Y」                    | 字段可能被隐藏，见[隐藏字段](https://docs.asktable.com/data/hidden-fields) |
| `SQL_SELECT_STAR_NOT_ALLOWED`   | 400  | 「不允许 SELECT \*，请显式列出字段」           | 问题里点名字段                                                       |
| `SQL_WRITE_NOT_ALLOWED`         | 400  | 「只允许 SELECT 查询」                   | 只做读查询                                                         |
| `SQL_UNQUALIFIED_TABLE`         | 400  | 「表 X 必须限定 schema（用 schema.table）」 | 到[表与字段备注](https://docs.asktable.com/data/semantics)补 schema   |
| `CHAT_PROCESSING`               | 409  | 「对话正在处理中」                         | 等当前这轮结束                                                       |
| `SERVICE_BUSY`                  | 503  | 「系统繁忙，请稍后重试」                      | 稍后重试                                                          |
| `DATA_AGENT_DELETED`            | 404  | 「当前会话绑定的智能体已被删除，请新建会话」            | 新建对话                                                          |
| `ROLE_DELETED`                  | 404  | 「当前会话绑定的角色已被删除，请重新选择角色或新建会话」      | 重新选角色或新建对话                                                    |
| `COMPACTION_NOT_SUPPORTED`      | 400  | 「该对话类型不支持压缩上下文」                   | 这类对话不做上下文压缩，属预期                                               |
| `COMPACTION_IN_PROGRESS`        | 409  | 「上下文正在压缩中，请稍候」                    | 等压缩结束                                                         |
| `COMPACTION_NOT_ENOUGH_CONTEXT` | 400  | 「对话内容还不够多，暂时无需压缩」                 | 属预期，不用处理                                                      |
| `FEEDBACK_NOT_ALLOWED`          | 400  | 「该对话不支持反馈」                        | 只有智能体对话支持反馈                                                   |
| `FEEDBACK_TARGET_INVALID`       | 404  | 「反馈目标消息不存在」                       | 刷新页面后重新提交                                                     |
| `FEEDBACK_LOGIN_REQUIRED`       | 403  | 「请登录后再提交反馈」                       | 登录后提交                                                         |

### 模型与联网搜索

| 错误码                         | HTTP | 界面提示原文                          | 处理                                                               |
| --------------------------- | ---- | ------------------------------- | ---------------------------------------------------------------- |
| `LLM_ERROR`                 | 400  | 「模型组 X 服务异常，请稍后重试」              | 上游异常，稍后重试；持续失败看上游状态                                              |
| `LLM_CONNECTION_ERROR`      | 400  | 「模型组 X 连接失败」                    | 核对 Base URL 和出网，见[配置大模型](https://docs.asktable.com/admin/models) |
| `LLM_BAD_RESPONSE`          | 400  | 「AI 服务返回了无效响应」                  | 换一个模型，或调整该模型的「供应商选项」                                             |
| `LLM_AUTH_ERROR`            | 400  | 「模型组 X 认证失败，请检查该模型组的 API 密钥或余额」 | 重填 API Key 或充值                                                   |
| `LLM_AGENT_BAD_RESPONSE`    | 400  | 「AI Agent 返回了无法解析的响应」           | 重发一次；持续失败换模型                                                     |
| `LLM_CONTENT_FILTERED`      | 400  | 「输入内容触发了内容安全审查，请修改后重试」          | 换问法；这是上游审查                                                       |
| `ASKTABLE_LLM_ONLY`         | 400  | 「此功能仅在配置官方 AI 代理通道时可用」          | 新建「AskTable 官方」类型的模型组并设为默认                                       |
| `WEB_SEARCH_NOT_CONFIGURED` | 400  | 「联网搜索未配置，请联系系统管理员在系统设置中配置」      | 到「系统设置」→「联网搜索」填齐三项                                               |

### 嵌入、报告与索引

| 错误码                        | HTTP | 界面提示原文              | 处理                                                      |
| -------------------------- | ---- | ------------------- | ------------------------------------------------------- |
| `EMBED_ORIGIN_NOT_ALLOWED` | 403  | 「该网站未被允许嵌入此智能体。」    | 把宿主页域名加进「允许域名」                                          |
| `EMBED_DISABLED`           | 403  | 「该嵌入地址已被停用。」        | 到智能体「嵌入」列表把开关打开                                         |
| `REPORT_PROCESSING`        | 409  | 「报告正在生成中」           | 等生成完成                                                   |
| `REPORT_FAILED`            | 400  | 「报告生成失败」            | 重新创建报告                                                  |
| `REPORT_STATUS_MISMATCH`   | 400  | 「报告状态不匹配：期望 X，当前 Y」 | 刷新后重试                                                   |
| `VALUE_INDEX_ERROR`        | 400  | 「AI 搜索索引出错」         | 重建索引，见[AI 索引](https://docs.asktable.com/data/ai-search) |
| `VALUE_INDEX_TIMEOUT`      | 400  | 「AI 搜索索引超时」         | 重试；字段太多就先缩小建立索引的范围                                      |
| `VALUE_INDEX_NOT_ENABLED`  | 400  | 「AI 搜索索引未启用」        | 见[AI 索引](https://docs.asktable.com/data/ai-search)      |

### 项目、授权与计费

| 错误码                             | HTTP | 界面提示原文      | 处理                                               |
| ------------------------------- | ---- | ----------- | ------------------------------------------------ |
| `PROJECT_LOCKED`                | 423  | 「项目已锁定」     | 联系平台管理员解除锁定                                      |
| `PROJECT_NOT_EMPTY`             | 403  | 「项目不为空」     | 先清空项目内资源                                         |
| `LICENSE_INVALID`               | 400  | 「许可证无效或已过期」 | 见[商业授权](https://docs.asktable.com/admin/license) |
| `ORDER_ALREADY_PAID`            | 409  | 「订单已支付」     | 不用重复支付                                           |
| `WECHAT_PAY_ERROR`              | 400  | 「微信支付出错」    | 重新下单                                             |
| `CONCURRENT_DEDUCTION_CONFLICT` | 409  | 「操作冲突，请重试」  | 重试                                               |
| `REDEEM_CODE_DISABLED`          | 409  | 「该兑换码已被作废」  | 换一个兑换码                                           |
| `REDEEM_CODE_EXPIRED`           | 410  | 「该兑换码已过期」   | 换一个兑换码                                           |
| `REDEEM_CODE_INVALID`           | 400  | 「兑换码无效」     | 核对兑换码是否完整                                        |

### 外部服务与系统

| 错误码                  | HTTP      | 界面提示原文         | 处理                          |
| -------------------- | --------- | -------------- | --------------------------- |
| `EXTERNAL_API_ERROR` | 500       | 「外部服务调用失败」     | 稍后重试                        |
| `AI_PROXY_ERROR`     | 500       | 「AI 代理服务出错」    | 稍后重试                        |
| `CRM_API_ERROR`      | 500       | 「CRM 服务出错」     | 稍后重试                        |
| `SMS_ERROR`          | 500       | 「短信服务出错」       | 检查「系统设置」→「手机号绑定」里的 SMS 网关配置 |
| `ASR_ERROR`          | 500       | 「语音识别服务出错」     | 重试；持续失败换一段音频                |
| `NOT_SUPPORT`        | 400       | 「功能 X 未启用或不支持」 | 确认该功能在当前部署形态和许可证下是否可用       |
| `VALIDATION_ERROR`   | 400 或 422 | 「数据验证失败」       | 按提示修正参数；请求体校验失败时是 422       |
| `PARAMETER_ERROR`    | 400       | 「参数 X 无效」      | 修正该参数                       |
| `CONFIG_ERROR`       | 400       | 「配置错误：X」       | 按提示改配置                      |
| `INTERNAL_ERROR`     | 500       | 「服务器内部错误」      | 稍后重试；持续失败带 trace id 提工单     |

### 没有对应文案的错误码

下面这些错误码在服务端有定义、也会返回对应 HTTP 状态，但前端没有对应的中文文案，界面统一显示兜底提示「操作失败，请稍后重试」。接口排查时靠 `code` 判断。

| 错误码                                   | HTTP                          | 界面提示         | 处理                                         |
| ------------------------------------- | ----------------------------- | ------------ | ------------------------------------------ |
| `ACCESSOR_AUTH_ERROR`                 | 400                           | 「操作失败，请稍后重试」 | 数据库账号或密码不对                                 |
| `ACCESSOR_DATABASE_NOT_FOUND`         | 400                           | 「操作失败，请稍后重试」 | 库名不对，或该库不存在                                |
| `ACCESSOR_NETWORK_ERROR`              | 400                           | 「操作失败，请稍后重试」 | 从 AskTable 服务器到数据库网络不通                     |
| `ACCESSOR_PERMISSION_DENIED`          | 400                           | 「操作失败，请稍后重试」 | 数据库账号权限不足                                  |
| `ACCESSOR_SQL_ERROR`                  | 400                           | 「操作失败，请稍后重试」 | 数据库执行 SQL 报错                               |
| `ACCESSOR_ENTERPRISE_ONLY`            | 403                           | 「操作失败，请稍后重试」 | 该数据源类型需要企业版授权                              |
| `TABLE_NOT_FOUND_IN_DATASOURCE`       | 404                           | 「操作失败，请稍后重试」 | 表在库里已被删除或改名                                |
| `DATASOURCE_META_ALREADY_INITIALIZED` | 409                           | 「操作失败，请稍后重试」 | 元数据已初始化，改用更新而不是初始化                         |
| `QUERY_TIMEOUT`                       | 504                           | 「操作失败，请稍后重试」 | 查询超时，放宽「全局查询超时（秒）」                         |
| `FILE_DOWNLOAD_TIMEOUT`               | 504                           | 「操作失败，请稍后重试」 | 文件下载超时，重试                                  |
| `FILE_RETRIEVAL_TRANSIENT`            | 503                           | 「操作失败，请稍后重试」 | 文件存储临时故障，重试                                |
| `TASK_TIMEOUT`                        | 504                           | 「操作失败，请稍后重试」 | 后台任务超时，重试                                  |
| `LLM_TIMEOUT`                         | 400                           | 「操作失败，请稍后重试」 | 模型请求超时，重试或换更快的模型                           |
| `LLM_RATE_LIMIT`                      | 400                           | 「操作失败，请稍后重试」 | 上游限流，稍后重试                                  |
| `LLM_PROVIDER_INTERNAL_ERROR`         | 400                           | 「操作失败，请稍后重试」 | 上游 SDK 内部异常，稍后重试                           |
| `SHARE_DISABLED`                      | 403                           | 「操作失败，请稍后重试」 | 分享已关闭或过期                                   |
| `CODE_EXECUTION_ERROR`                | 400                           | 「操作失败，请稍后重试」 | Python 沙箱执行失败，换个问法                         |
| `STUCK_REFRESH_RECOVERED`             | 500                           | 「操作失败，请稍后重试」 | 刷新任务被中断后自动恢复，重试即可                          |
| `SMS_GATEWAY_REJECTED`                | 502                           | 「操作失败，请稍后重试」 | 短信网关拒绝了请求，核对手机号与网关账户                       |
| `WORKBOOK_*` 家族                       | 多为 422，少数 400、403、404、409、413 | 「操作失败，请稍后重试」 | 工作簿的字段类型、行数、批次、导入映射等校验失败，按服务端 `message` 定位 |

## 下一步

- 按现象快速定位：[常见问题](https://docs.asktable.com/reference/faq)
- 服务起不来、页面打不开：[故障排查](https://docs.asktable.com/reference/troubleshooting)
- 授权相关错误：[商业授权](https://docs.asktable.com/admin/license)