跳到正文
AskTable

文档反馈

当前页面错误码/reference/error-codes

0 / 5,000

反馈将发送给维护团队。

前往控制台
前往控制台
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—
4xx 与 5xx4xx 是业务异常（不触发告警），5xx 会触发告警—

出问题怎么判断

资源与配额

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

数据源与元数据

错误码HTTP界面提示原文处理
ACCESSOR_ERROR400「数据库连接失败」核对连接信息，见连接数据源
ACCESSOR_CONNECTION_ERROR400「无法连接到数据库」核对地址、网络和账号；云端部署确认已加白名单
DATASOURCE_META_PROCESSING409「数据源元数据正在处理中」等元数据解析完成
DATASOURCE_META_NOT_READY400「数据源元数据未就绪」先完成元数据解析
DATASOURCE_CONFIG_ERROR400「数据源配置错误」到数据源「设置」里检查配置
TABLE_REFRESH_ALREADY_RUNNING409「另一次刷新正在进行中，请等其完成再试」等本次刷新结束
WORKBOOK_NAME_CONFLICT409「数据源名称「X」已存在，换个名字试试」换一个数据源名称
WORKBOOK_READ_ONLY403「飞书同步工作簿为只读，不能在 AskTable 内修改结构或数据」改到飞书侧改
WORKBOOK_FEISHU_SYNC_RUNNING409「飞书同步正在进行中，请稍后再试」等同步结束
WORKBOOK_FEISHU_SOURCE_NOT_FOUND404「未找到飞书同步配置」重新建一次同步配置
WORKBOOK_FEISHU_CREDENTIAL_INVALID422「飞书应用凭证无效，请检查 App ID 和 App Secret」重填凭证
WORKBOOK_FEISHU_APP_TOKEN_INVALID422「飞书多维表格 App Token 无效或无权访问」确认该表对应用可见
WORKBOOK_FEISHU_INVALID_URL422「链接无法识别为多维表格，请粘贴多维表格页面的完整 URL」粘完整 URL 再试
WORKBOOK_FEISHU_TABLE_MISSING422「飞书表 X 不存在或无权访问」重新选表
WORKBOOK_FEISHU_NO_TABLE_SELECTED422「请至少选择一个飞书表」至少勾一张表

文件上传

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

认证与用户

错误码HTTP界面提示原文处理
AUTH_ERROR401「认证失败」重新登录
TOKEN_EXPIRED401「登录已过期，请重新登录」重新登录
TOKEN_INVALID401「登录凭证无效」重新登录；API 调用换一个新 key
INVALID_CREDENTIALS401「邮箱或密码错误」核对账号密码
PROVIDER_AUTH_FAILED401「第三方登录失败」见企业身份登录
PASSWORD_MISMATCH401「原密码不正确」重填原密码
USER_DISABLED403「用户已被禁用」找管理员在左侧「用户」里处理
VERIFICATION_CODE_INVALID401「验证码无效或已过期」重新获取验证码

权限与语义层

错误码HTTP界面提示原文处理
PERMISSION_DENIED403「权限不足」补项目成员身份或数据范围，见权限与数据安全
SEMANTIC_WRITE_PERMISSION_DENIED403「无权编辑语义层，需要管理员权限」由项目负责人或项目管理员操作
SEMANTIC_WRITE_ROLE_CONFLICT400「语义层写入不能与会话角色同时使用」先取消会话角色再开启写入
SEMANTIC_VALIDATION_FAILED400「语义层校验失败，无法导出 dbt YAML」按校验提示修正后再导出
SEMANTIC_EXPORT_FAILED400「dbt YAML 导出失败」修正语义层后重试
ROLE_IN_USE409「角色正被 N 个智能体白名单引用，无法删除」先从相关智能体的白名单里移除该角色

对话与查询

错误码HTTP界面提示原文处理
CHAT_ERROR400「对话出错」重发一次；持续失败带上 trace id 提工单
NO_DATA_TO_QUERY400「没有可查询的数据表或字段」确认数据源已接入并选过表
CANNOT_HANDLE400「查询过于复杂，请简化后重试」拆成几步问
SQL_UNKNOWN_TABLE400「数据源中找不到表 X（schema Y）」到数据源详情页重新选表
SQL_UNKNOWN_FIELD400「表 X 上找不到字段 Y」字段可能被隐藏，见隐藏字段
SQL_SELECT_STAR_NOT_ALLOWED400「不允许 SELECT *，请显式列出字段」问题里点名字段
SQL_WRITE_NOT_ALLOWED400「只允许 SELECT 查询」只做读查询
SQL_UNQUALIFIED_TABLE400「表 X 必须限定 schema（用 schema.table）」到表与字段备注补 schema
CHAT_PROCESSING409「对话正在处理中」等当前这轮结束
SERVICE_BUSY503「系统繁忙，请稍后重试」稍后重试
DATA_AGENT_DELETED404「当前会话绑定的智能体已被删除，请新建会话」新建对话
ROLE_DELETED404「当前会话绑定的角色已被删除，请重新选择角色或新建会话」重新选角色或新建对话
COMPACTION_NOT_SUPPORTED400「该对话类型不支持压缩上下文」这类对话不做上下文压缩，属预期
COMPACTION_IN_PROGRESS409「上下文正在压缩中，请稍候」等压缩结束
COMPACTION_NOT_ENOUGH_CONTEXT400「对话内容还不够多，暂时无需压缩」属预期，不用处理
FEEDBACK_NOT_ALLOWED400「该对话不支持反馈」只有智能体对话支持反馈
FEEDBACK_TARGET_INVALID404「反馈目标消息不存在」刷新页面后重新提交
FEEDBACK_LOGIN_REQUIRED403「请登录后再提交反馈」登录后提交

模型与联网搜索

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

嵌入、报告与索引

错误码HTTP界面提示原文处理
EMBED_ORIGIN_NOT_ALLOWED403「该网站未被允许嵌入此智能体。」把宿主页域名加进「允许域名」
EMBED_DISABLED403「该嵌入地址已被停用。」到智能体「嵌入」列表把开关打开
REPORT_PROCESSING409「报告正在生成中」等生成完成
REPORT_FAILED400「报告生成失败」重新创建报告
REPORT_STATUS_MISMATCH400「报告状态不匹配：期望 X，当前 Y」刷新后重试
VALUE_INDEX_ERROR400「AI 搜索索引出错」重建索引，见AI 索引
VALUE_INDEX_TIMEOUT400「AI 搜索索引超时」重试；字段太多就先缩小建立索引的范围
VALUE_INDEX_NOT_ENABLED400「AI 搜索索引未启用」见AI 索引

项目、授权与计费

错误码HTTP界面提示原文处理
PROJECT_LOCKED423「项目已锁定」联系平台管理员解除锁定
PROJECT_NOT_EMPTY403「项目不为空」先清空项目内资源
LICENSE_INVALID400「许可证无效或已过期」见商业授权
ORDER_ALREADY_PAID409「订单已支付」不用重复支付
WECHAT_PAY_ERROR400「微信支付出错」重新下单
CONCURRENT_DEDUCTION_CONFLICT409「操作冲突，请重试」重试
REDEEM_CODE_DISABLED409「该兑换码已被作废」换一个兑换码
REDEEM_CODE_EXPIRED410「该兑换码已过期」换一个兑换码
REDEEM_CODE_INVALID400「兑换码无效」核对兑换码是否完整

外部服务与系统

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

没有对应文案的错误码

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

错误码HTTP界面提示处理
ACCESSOR_AUTH_ERROR400「操作失败，请稍后重试」数据库账号或密码不对
ACCESSOR_DATABASE_NOT_FOUND400「操作失败，请稍后重试」库名不对，或该库不存在
ACCESSOR_NETWORK_ERROR400「操作失败，请稍后重试」从 AskTable 服务器到数据库网络不通
ACCESSOR_PERMISSION_DENIED400「操作失败，请稍后重试」数据库账号权限不足
ACCESSOR_SQL_ERROR400「操作失败，请稍后重试」数据库执行 SQL 报错
ACCESSOR_ENTERPRISE_ONLY403「操作失败，请稍后重试」该数据源类型需要企业版授权
TABLE_NOT_FOUND_IN_DATASOURCE404「操作失败，请稍后重试」表在库里已被删除或改名
DATASOURCE_META_ALREADY_INITIALIZED409「操作失败，请稍后重试」元数据已初始化，改用更新而不是初始化
QUERY_TIMEOUT504「操作失败，请稍后重试」查询超时，放宽「全局查询超时（秒）」
FILE_DOWNLOAD_TIMEOUT504「操作失败，请稍后重试」文件下载超时，重试
FILE_RETRIEVAL_TRANSIENT503「操作失败，请稍后重试」文件存储临时故障，重试
TASK_TIMEOUT504「操作失败，请稍后重试」后台任务超时，重试
LLM_TIMEOUT400「操作失败，请稍后重试」模型请求超时，重试或换更快的模型
LLM_RATE_LIMIT400「操作失败，请稍后重试」上游限流，稍后重试
LLM_PROVIDER_INTERNAL_ERROR400「操作失败，请稍后重试」上游 SDK 内部异常，稍后重试
SHARE_DISABLED403「操作失败，请稍后重试」分享已关闭或过期
CODE_EXECUTION_ERROR400「操作失败，请稍后重试」Python 沙箱执行失败，换个问法
STUCK_REFRESH_RECOVERED500「操作失败，请稍后重试」刷新任务被中断后自动恢复，重试即可
SMS_GATEWAY_REJECTED502「操作失败，请稍后重试」短信网关拒绝了请求，核对手机号与网关账户
WORKBOOK_* 家族多为 422，少数 400、403、404、409、413「操作失败，请稍后重试」工作簿的字段类型、行数、批次、导入映射等校验失败，按服务端 message 定位

下一步