错误码 - AskTable

界面上看到的是中文提示，接口里看到的是错误码——两者由同一份定义驱动。这一页是错误码的完整索引：按错误码查 HTTP 状态、界面提示原文和处理动作。

开始前

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

关键约束

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

{
  "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`	—
scope 检查不通过	HTTP 401，响应体是 `{"detail": "Insufficient scopes"}`，没有 `code` 字段；前端映射成 `VIEWER_READONLY`	—
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	「数据库连接失败」	核对连接信息，见连接数据源
`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	「第三方登录失败」	见企业身份登录
`PASSWORD_MISMATCH`	401	「原密码不正确」	重填原密码
`USER_DISABLED`	403	「用户已被禁用」	找管理员在左侧「用户」里处理
`VERIFICATION_CODE_INVALID`	401	「验证码无效或已过期」	重新获取验证码

权限与语义层

错误码	HTTP	界面提示原文	处理
`PERMISSION_DENIED`	403	「权限不足」	补项目成员身份或数据范围，见权限与数据安全
`VIEWER_READONLY`	401	「当前为所有人可见的公开项目，不能修改资源配置」	切到自己的私有项目
`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」	字段可能被隐藏，见隐藏字段
`SQL_SELECT_STAR_NOT_ALLOWED`	400	「不允许 SELECT *，请显式列出字段」	问题里点名字段
`SQL_WRITE_NOT_ALLOWED`	400	「只允许 SELECT 查询」	只做读查询
`SQL_UNQUALIFIED_TABLE`	400	「表 X 必须限定 schema（用 schema.table）」	到表与字段备注补 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 和出网，见配置大模型
`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 索引
`VALUE_INDEX_TIMEOUT`	400	「AI 搜索索引超时」	重试；字段太多就先缩小建立索引的范围
`VALUE_INDEX_NOT_ENABLED`	400	「AI 搜索索引未启用」	见AI 索引

项目、授权与计费

错误码	HTTP	界面提示原文	处理
`PROJECT_LOCKED`	423	「项目已锁定」	联系平台管理员解除锁定
`PROJECT_NOT_EMPTY`	403	「项目不为空」	先清空项目内资源
`LICENSE_INVALID`	400	「许可证无效或已过期」	见商业授权
`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` 定位

下一步

按现象快速定位：常见问题
服务起不来、页面打不开：故障排查
授权相关错误：商业授权

​开始前

​关键约束

​出问题怎么判断

​资源与配额

​数据源与元数据

​文件上传

​认证与用户

​权限与语义层

​对话与查询

​模型与联网搜索

​嵌入、报告与索引

​项目、授权与计费

​外部服务与系统

​没有对应文案的错误码

​下一步

开始前

关键约束

出问题怎么判断

资源与配额

数据源与元数据

文件上传

认证与用户

权限与语义层

对话与查询

模型与联网搜索

嵌入、报告与索引

项目、授权与计费

外部服务与系统

没有对应文案的错误码

下一步