跳到主要内容

错误码参考

响应结构​

普通接口统一返回：

{
  "code": 40013,
  "msg": "签名验证失败，请检查验证参数是否正确",
  "data": null
}
字段说明
code业务码。成功为 200；失败为下方错误码
msg可直接展示给调用方的错误描述
data成功时的业务数据；失败通常为 null
HTTP 状态与业务码

多数网关业务错误（认证失败、无权限、IP 拦截、WAF 拦截）返回 HTTP 200，需要读取 code 判断结果。例外：authType=jwt 的认证/授权失败返回 401/403/503；限流返回 429，熔断返回 503，下游不可用返回 503，超时返回 504。

网关顶层异常处理器输出的 code 是字符串（如 "50001"），而过滤器与业务接口通常输出数值。客户端解析时应同时兼容字符串与数字。

认证与授权（40001–40033）​

错误码消息常见原因排查建议
40001接口不存在或已下线路径/方法不匹配、接口未发布、路由未同步核对发布环境与路径前缀；检查网关路由
40002认证失败，应用无接口权限应用未被授权该接口在应用授权或审批中补授权
40003该接口授权已过期授权为有效期类型且已到期续期或改为永久授权
40006该接口已下线发布快照被下线重新上线并同步环境
40007该接口调用次数已达上限授权/订阅配额用尽调整限额或次日重试
40008Header 中 X-AppKey 不能为空简单认证缺少 AppKey补 X-AppKey
40009认证参数不能为空签名认证缺少 AppKey/Timestamp/Sign补齐四个认证头
40010时间戳已过期 / Nonce 已失效时间偏差超过 10 分钟，或 Nonce 重放校准时钟；每次请求生成新 Nonce
40012该 IP 地址不在有效范围内接口级 IP 规则拦截检查规则类型（黑/白名单）与客户端出口 IP
40013签名验证失败AppSecret 错误、签名串拼接错误、算法不一致对照签名指南逐项核对
40018该 IP 地址不在认证授权范围内应用凭证级 IP 白名单拦截在应用配置中补充出口 IP
40019应用已禁用应用被停用启用应用
40020该应用未启用 MCP访问 /mcp/{appCode} 但应用未开启 MCP在应用设置中启用 MCP
40021订阅已失效或被冻结订阅过期、退订或冻结检查订阅状态与有效期
40022目标地址不被允许访问代理模式目标命中出站黑名单调整目标地址或安全策略
40023订阅日调用量配额已超出订阅日限额用尽次日重试或调整限额
40024Header 中认证参数 Authorization 不能为空OAuth2 接口未携带 Authorization: Bearer <token>，或 Bearer 前缀拼写错误先调用 /oauth2/token 换取 token 后补请求头
40025Token 无效或已过期token 过期、被篡改、来自其它环境，或应用已被删除重新换取 token；核对 token 环境来源
40026Token 已失效，请重新获取token 被吊销（服务端会话已删除）重新换取 token
40028Header 中认证参数 Authorization 缺少 Bearer TokenJWT 接口未携带 Authorization，或值为空补 Authorization: Bearer <token>
40029JWT 无效或已过期签名、iss、aud、exp、typ、kid 或 claims 不合法；Authorization 格式错误对照 JWT 企业 IdP 认证 的 claims 要求逐项核对
40030身份提供方暂不可用，请稍后重试JWT 功能未开启，或 IdP / JWKS 不可达检查 apigo.jwt.enabled 与 IdP 连通性，按 Retry-After 重试
40031JWT 主体未绑定任何应用token 主体与凭证绑定不一致在凭证中配置 JWT 身份绑定，确认 subject 完全一致
40032JWT 权限范围不足scope 不满足（预留）检查 IdP 签发的 scope
40033该应用已绑定企业IdP身份，其他静态凭证不可用已绑定 JWT 的应用在开关开启时仍用 X-AppKey / appSecret 调用改用 IdP 签发的 Bearer token，或关闭 apigo.jwt.disable-static-credentials-for-bound-apps

OAuth2 token 端点 /oauth2/token 不使用上表错误码，而是返回 OAuth2 标准错误体（invalid_request / unsupported_grant_type / invalid_client / server_error），见 OAuth2 客户端凭证认证。

JWT 认证（authType=jwt）使用标准 HTTP 语义：401（token 缺失/无效）、403（主体未绑定/应用禁用/IP/无授权）、503（IdP 不可用）。响应体仍为 {code,msg}，并可能附加 error / error_description 与 WWW-Authenticate。接口不存在或已下线在认证前判定，仍返回 HTTP 200。详见 JWT 企业 IdP 认证。

401/402 语义：401 表示登录已失效，402 表示用户未登录。二者用于管理端 JWT 会话，不出现在开放接口签名链路。

参数与 SQL（41000–41013）​

错误码消息说明
41000必传参数不能为空接口定义的必填参数缺失
41006该接口地址已被使用保存时路径 + 方法冲突（管理端也返回 50011）
41007多选多参数至少传其中一个参数校验规则不满足
41008请求参数值格式错误类型转换失败，如数字参数传了文本
41009多选一参数只能传其中一个互斥参数同时传入
41010分页参数不能为空分页接口缺少页码或页大小
41011请求参数名不合法参数名使用了运行态保留字
41012SQL 插值参数不合法使用了不安全的 ${} 插值，应改为 #{} 预编译
41013编排规则校验失败LAYOUT 模式的字段编排配置不合法
40011SQL 执行失败SQL 语法、表/字段不存在、数据源连接异常
40014SQL 含特殊字符- 等字符未用双引号包裹
40015不支持该类型操作当前模式不支持该操作（如非查询 SQL 走缓存）
40016第三方接口调用失败代理目标返回错误或连接失败

系统与数据源（5xxxx）​

错误码消息说明
50001系统繁忙未捕获异常的统一兜底
50002系统升级中服务维护状态
50003下游服务实例连接异常执行服务不可达
50004接口响应时间超时下游处理超时
50010登录失败，请检查数据库连接登录时查询用户失败
50011该接口地址已存在保存接口时路径冲突
51001数据源初始化失败连接池创建失败
51002查询 schema / 索引列表失败数据源配置或权限问题
51003插件名称不能为空驱动 getName() 返回空
51004插件名称已存在两个驱动注册了相同类型名
51005查询索引失败元数据读取失败
52005请求参数缺少SQL 构建阶段缺少必要参数
55000插件异常数据源驱动内部错误
44001空指针异常网关处理链路空指针，需查看日志
45001数据库密码解密失败数据源密码密文与密钥不匹配

权限与操作（43xxx）​

错误码消息说明
43000无效操作当前状态下不允许该操作
43001无效的 API接口不存在或已删除
43002API 已发布，请先下线已发布接口不允许直接编辑
43003没有操作权限当前用户无该项目/资源的操作权限

MCP 协议错误​

MCP 入口返回 JSON-RPC 2.0 错误对象，不使用 {code,msg,data} 结构：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}
错误码含义场景
-32600Invalid Request请求体不是合法 JSON-RPC，或方法名缺失
-32601Method Not Found调用了未实现的方法
-32602Invalid Params参数缺失、类型错误、工具未授权
-32603Internal Error工具执行失败、权限不足、响应体过大、网关内部异常

MCP 请求发生限流或熔断时，HTTP 状态分别为 429 / 503，响应体仍为 JSON-RPC 错误对象。

License 错误（L001–L015）​

License 校验失败会阻断服务启动或触发退出，错误码见 部署拓扑与 License。

排查顺序​

  1. 先看 HTTP 状态：429 查限流规则，503 查熔断与实例健康，504 查超时配置。
  2. 再看业务码：认证类（400xx）优先核对 AppKey/签名/IP；参数类（410xx）核对入参与类型。
  3. 结合 traceId：响应头 X-TraceId 可用于在调用日志中定位完整请求链路。
  4. 确认发布状态：40001、40006 多数是环境未同步或接口未上线。
  5. 检查运行态同步：规则或路由修改后未生效，执行一次手动对账。

相关文档​