错误码

管理接口、Agent、OpenAPI 和采集的 POST 请求共用同一个信封，这一页列出全部 code。

{ "code": 40001, "message": "给人看的说明", "data": null }

• HTTP 状态与 code 一起返回，调用方以 code 判断。code 不为 0 时 data 可以为空。
• message 按请求头 Accept-Language 选择简体中文或英文，可以直接展示给用户。里面不会有 SQL、连接串和密钥。
• 每个响应都带 X-Request-Id，报问题时附上它，维护者可以在服务端日志里找到这一次请求。

code	HTTP	含义	典型场景
0	200	成功
40001	400	参数不合法	日期跨度超过模块上限；维度不在允许的列表里；自定义 SQL 被拒绝；看板卡片不合法；写接口不是 JSON；验证码错误或过期
40002	400	功能未配置	没配 AI 时提问；没配 SMTP 或 site.public_url 时找回密码；没配 IP 库时调用依赖它的接口
40003	400	引导未完成	还没有 Redis 或管理员时上报、登录
40101	401	未认证	没登录、会话失效；写入密钥或接口密钥无效、已停用、已轮换；项目关了采集。登录失败的提示固定是「账号或密码错误」
40301	403	没有权限	没有这个项目的权限；非管理员调用管理操作；演示用户的写操作；读别人的 Agent 对话或私有看板
40401	404	不存在	项目、看板、会话、实验不存在或已删除；接口前缀下没有这个路由。查询没有结果时返回空数组，不用这个码
40901	409	冲突	用户名或项目标识重复；两个人同时走引导创建管理员；引导里已经选过是否创建演示项目，又选一次；删除仍被项目引用的分片
41301	413	请求体过大	采集请求超过 1MB（解压后也算）；回放单块超过 2MB
42901	429	太频繁或超限	登录失败过多；查看写入密钥时密码输错过多；OpenAPI 超过每分钟 60 次；重置邮件发得太频繁；Agent 当日次数用完；采集队列达到上限
50001	500	内部错误	没有预料到的异常，请带上 request_id 反馈
50002	504	查询超时	统计查询超过了这个模块的时限（普通查询 15 秒，漏斗、留存、路径、归因、自定义 SQL 30 秒）
50301	503	依赖不可用	项目所在的分片、Redis 或模型服务连不上

几个特例

• 像素 GET /sa.gif 无论成败都返回 GIF，不用这张表的 HTTP 状态。
• 采集批内个别事件被过滤时仍是 0，data.accepted 只数写入的条数。
• Agent 的回答是流：流开始之后才失败时，HTTP 状态已经是 200，错误用 error 事件带同样的 code 和 message。开始之前的错误（没配模型、次数用完、没有权限）仍是普通 JSON。
• 概览里会话部分超时不算错误：code 是 0，data.partial 里标出缺的部分，界面显示「计算超时」。

处理建议

code	调用方该做什么
40001	看 message 修参数，不要重试
40101	检查密钥或重新登录，不要重试
40301	找管理员授权
42901	退避之后再试；OpenAPI 调用方加缓存
50002	缩小日期范围或减少筛选条件
50001、50301	稍后重试；持续出现时带 request_id 联系管理员，见 运维与排障