GraphForge.AI

错误码速查

GraphForge 全部错误响应统一格式：

{ "detail": "错误信息（中英文混合）" }

部分接口使用 { "success": false, "message": "..." } 风格（历史遗留，逐步收敛中）。

常见 HTTP 状态码

码含义典型原因处理
400请求格式错必填字段缺失 / 类型错 / 业务逻辑校验失败看 detail 修改 payload
401未鉴权Token 缺失 / 失效 / TTL 过期重新调 /auth/login 拿新 token
403鉴权但无权用户对该资源无访问权（非 owner 且非 admin）联系 admin 加权限 / 用 POST /api/permissions/graphs/{id}/members
404资源不存在graph_id / metric_id / job_id 错或已删核对 id；删了的资源不会自动恢复
422Pydantic 校验失败字段类型 / 长度 / 枚举值不符 schema看 detail.errors 数组，每条含 loc/msg/type
429速率超限触发 认证 文档的速率表等 60s 重试；或申请提升配额
500服务端异常后端 bug / LLM 服务异常 / DB 连接断重试 1-2 次；持续报联系支持
501未实现该 endpoint 在文档列出但功能未 ship（如 PUT/DELETE /ingestion/jobs/{id}）看 detail 确认 Sprint 计划
502上游超时LightRAG 首次冷启动 > 120s 代理超时；后端仍会完成等 1 分钟后重发，第二次走缓存秒回

业务特定错误

Endpoint错误含义
POST /metrics/.../executeFormulaParseError指标公式不在 10 模式 dispatcher 内
POST /metrics/.../executeMissingBindingError指标没建物理绑定，无法执行
POST /metrics/.../executeUnsafeFilterClauseErrorfilter_clause 含 DDL/DML 被 sqlglot 拦截
POST /ingestion/jobsmapping_yaml validation failedYAML 语法错或列规则错
POST /warehouse/connectionspg_mirror connections must not provide a DSNpg_mirror 类型必须 dsn=null
DELETE /warehouse/connections/{id}422删默认 pg_mirror 被拒；或外键有 IngestionJob 引用

鉴权调试 checklist

收到 401 时按以下顺序排查：

  1. 请求头是否含 Authorization: Bearer <token>（注意 Bearer 后必须有空格）
  2. Token 是不是从 /auth/login 返回的 token 字段（不是 user_id）
  3. Token 是否过期 → 调 GET /api/auth/me 验证；401 即过期
  4. 服务端 JWT_SECRET_KEY 是否变了（重启时如果没配 env，会用随机 key，所有老 token 失效）
  5. 跨域调用时检查 CORS 是否含你的 origin

联系支持

仍排查不出 → 邮件 marketing@yrules.com，附 request_id（从响应头 X-Request-ID 取）+ 完整 curl 命令（脱敏 token / password）。