错误码对照表¶

文档版本: 1.1.0 最后更新: 2026-10-15 适用版本: v3.3.3+ 作者: AI Assistant

JAiRouter 使用标准化的错误码系统来标识各种错误情况，便于客户端进行错误处理。

⚠️ 响应形状按入口面不同：/api/**（控制台面）用下面表格里的 RouterResponse 形状（errorCode 字段）；/v1/**（OpenAI 面）用嵌套的 {"error":{"message","type","code"}}（见 统一 API 接口）；/v1/messages（Anthropic 面）用 Anthropic 的 {"type":"error","error":{...}} 形状。另有两个已知例外不走本表：管理面限流 429 返回 {"code":"RATE_LIMIT_EXCEEDED","message":...}（扁平体、没有 error 包裹）；异常处理器兜底返回数字码（如 {"code":"500"}）。

📌 本表的权威来源是代码：本表与 common/constants/ErrorCode.java（错误码注册表，62 个会被真正发出的码）逐条对账， 由 scripts/docs/check-error-codes.py 在 CI 里双向校验 —— 文档漏列一个注册表里的码、或文档列了一个发不出来的码，都会判红。 每个码的「状态由哪条链决定」也登记在注册表里（渲染路径），因此改码名/改状态前先改注册表。

错误响应格式¶

{
  "success": false,
  "message": "错误描述",
  "errorCode": "ERROR_CODE",
  "data": null
}

HTTP 状态码映射¶

认证错误码 (Authentication)¶

HTTP 状态码: 401 Unauthorized

这一节的码由认证异常承载（注册表里的渲染路径是认证链）：客户端可见状态来自异常携带的 401， 不是由错误码命名规则推导的 —— 例如 INVALID_API_KEY 的规则链推导值是 400，但客户端拿到的是 401。

示例响应:

{
  "success": false,
  "message": "无效的API Key",
  "errorCode": "INVALID_API_KEY",
  "data": null
}

授权错误码 (Authorization)¶

HTTP 状态码: 403 Forbidden

⚠️ INSUFFICIENT_PERMISSIONS / ACCESS_DENIED / FORBIDDEN_RESOURCE 曾在 AuthorizationException 里声明，但 全仓没有发出点（其工厂方法只被单元测试调用）⇒ 已随未接线代码一并删除（#406），本表不列：客户端照它们写分支永远命中不到。 真正的 403 由 Spring Security 的授权链与上表的 FORBIDDEN 承担。 BUILTIN_READONLY 由 AdapterConfigController 的 PUT/DELETE 内置分支显式写成 403；按 issue #405 的混合方案，同码的规则链推导值也已对齐为 403 ⇒ 两端一致。

资源错误码 (Resource)¶

HTTP 状态码: 404 Not Found

ApiException.resolveStatus 还会把任何以 _NOT_FOUND 结尾的未登记码按规则映射为 404； 上表是已登记的四个码。

请求校验错误码 (Validation)¶

HTTP 状态码: 400 Bad Request

⚠️ RESTART_REQUIRED 的端点实测值与规则链推导值现在都是 400 —— 按 issue #405 的混合方案， 每条链先按自己的语义定状态（本码 = 请求校验语义 400），再把两端对齐：规则链对同码原先推导 403， 已改为 400。同一方案把 BUILTIN_READONLY 定为授权语义 403，故它已移入「授权错误码」一节。 上一版还列过 VALIDATION_ERROR（只是 ValidationFailureType 的枚举值，从不作为响应码发出）、 INVALID_PARAMETER / MISSING_PARAMETER / INVALID_FORMAT（全库无匹配）—— 均已从本表移除。

业务冲突错误码 (Business)¶

HTTP 状态码: 409 Conflict

冲突码的真实形态是 CONFLICT_STATE（由异常映射）以及共用前缀的端点级变体 CONFLICT_EXISTS / CONFLICT_BUILTIN；不存在裸 CONFLICT。 ApiException.resolveStatus 把任何 CONFLICT* 归 409。

限流错误码 (Rate Limit)¶

HTTP 状态码: 429 Too Many Requests（管理面）· 401（API Key 校验链）

⚠️ 同一个码在两条真实路径上对应两个状态（issue #404，待裁定）： ① 管理面限流器（AdminApiRateLimiter）直接写 429 扁平体 {"code":"RATE_LIMIT_EXCEEDED","message":...}； ② API Key 校验链（ApiKeyValidator → FullValidationResult.toException()）把它装进 AuthenticationException， 客户端拿到 401。按状态码分支的客户端需要同时处理这两种情况。

响应头没有 X-RateLimit-Reset / X-RateLimit-Remaining（全仓无此头）；配额超限实际写 Retry-After 与 X-Quota-*（limit / remaining / window）。原表里的 GLOBAL_RATE_LIMIT / SERVICE_RATE_LIMIT / INSTANCE_RATE_LIMIT 全库无匹配，已删除。

服务与系统错误码 (System)¶

HTTP 状态码: 500 Internal Server Error

⚠️ RULE_COMPILATION_FAILED 与上节的三个授权码同类：曾在 SanitizationException 里声明、 全仓没有发出点（工厂方法只被单元测试调用）⇒ 已随未接线代码一并删除（#406），本表不列。规则编译失败今天表现为 SANITIZATION_FAILED 或 INVALID_SANITIZATION_RULE。 上一版列过的 CONFIGURATION_ERROR / DATABASE_ERROR / CACHE_ERROR 同样全库无匹配：配置、数据库、 缓存故障都表现为 INTERNAL_ERROR（也是解析器对任何不匹配规则的码的兜底值）。

服务不可用 (Service Unavailable)¶

HTTP 状态码: 503 Service Unavailable

下游服务错误码 (Downstream)¶

HTTP 状态码: 原样取下游返回的状态（常见 502/503/504；下游返回 401 时归一到 401 认证分支）

这个码的 HTTP 状态不固定：SecurityExceptionHandler 直写错误体时原样取下游返回的状态码 ⇒ 注册表里它的状态登记为「随上下文」（不是 502/503 之一）。 上一版用 5xx / 502 / 503 / 504 当「错误码模式」列出，那既不是码也不是本网关发出的值。

错误处理最佳实践¶

1. 客户端错误处理¶

// JavaScript 示例
async function handleApiResponse(response) {
  const data = await response.json();

  if (!data.success) {
    const code = data.errorCode ?? data.error?.code;

    switch (code) {
      case 'INVALID_API_KEY':
      case 'EXPIRED_API_KEY':
      case 'EMPTY_API_KEY':
      case 'JWT_EXPIRED':
      case 'JWT_INVALID':
      case 'JWT_BLACKLISTED':
        // 需要重新认证
        window.location.href = '/login';
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // 退避后重试（管理面 429 会带 Retry-After）
        await sleep((Number(response.headers.get('Retry-After')) || 1) * 1000);
        return retryRequest();
      default:
        showError(data.message ?? data.error?.message);
    }
    return;
  }

  return data.data;
}

2. 服务端错误处理¶

// Java 示例
@RestControllerAdvice
public class ErrorHandler {

    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity<ErrorResponse> handleAuthException(AuthenticationException ex) {
        // 状态码取异常携带的值（注册表里的认证链路径）
        return ResponseEntity.status(ex.getHttpStatus())
            .body(new ErrorResponse(ex.getMessage(), ex.getErrorCode()));
    }

    @ExceptionHandler(ApiException.class)
    public ResponseEntity<ErrorResponse> handleApiException(ApiException ex) {
        return ResponseEntity.status(ex.getStatus())
            .body(new ErrorResponse(ex.getMessage(), ex.getErrorCode()));
    }
}

3. 错误日志记录¶

// 记录错误日志
log.error("认证失败: errorCode={}, message={}",
    ex.getErrorCode(), ex.getMessage());

变更记录¶

最后更新: 2026-10-15