Error Codes Reference¶

Document Version: 1.1.0 Last Updated: 2026-10-15 Applicable Version: v3.3.3+ Author: AI Assistant

JAiRouter uses a standardized error code system to identify various error conditions. All error responses include an error code field for client-side error handling.

⚠️ The response shape depends on the entry surface: /api/** (console) uses the RouterResponse shape shown below (errorCode field); /v1/** (OpenAI surface) uses a nested {"error":{"message","type","code"}} (see Universal API); /v1/messages (Anthropic surface) uses Anthropic's {"type":"error","error":{...}} shape. Two known exceptions do not use this table: the admin rate limiter returns a flat {"code":"RATE_LIMIT_EXCEEDED","message":...} body with 429, and exception-handler fallbacks return numeric codes (for example {"code":"500"}).

📌 Code is the authority for this table: it is reconciled entry by entry against common/constants/ErrorCode.java (the error-code registry, 62 codes that are actually emitted), and scripts/docs/check-error-codes.py verifies it both ways in CI — a registry code missing from this table, or a table code that can never be emitted, fails the build. Which chain decides each code's HTTP status is registered too (its render path), so change the registry before changing a code name or status.

Error Response Format¶

{
  "success": false,
  "message": "Error description",
  "errorCode": "ERROR_CODE",
  "data": null
}

HTTP Status Code Mapping¶

Authentication Error Codes¶

HTTP Status: 401 Unauthorized

The codes in this section are carried by authentication exceptions (their render path in the registry is the authentication chain): the client-visible status comes from the exception's 401, and is not derived from the code's naming rule — INVALID_API_KEY, for example, would resolve to 400 by rule, but clients receive 401.

Example Response:

{
  "success": false,
  "message": "Invalid API Key",
  "errorCode": "INVALID_API_KEY",
  "data": null
}

Authorization Error Codes¶

HTTP Status: 403 Forbidden

⚠️ INSUFFICIENT_PERMISSIONS / ACCESS_DENIED / FORBIDDEN_RESOURCE are declared in AuthorizationException but have no emission site anywhere in the repository (their factory methods are only called by unit tests) ⇒ they were removed from this table: a client branching on them would never match. Real 403s come from the Spring Security authorization chain and from FORBIDDEN above.

Resource Error Codes¶

HTTP Status: 404 Not Found

ApiException.resolveStatus also maps any unregistered code ending in _NOT_FOUND to 404 by rule; the table above lists the four registered codes.

Validation Error Codes¶

HTTP Status: 400 Bad Request

⚠️ BUILTIN_READONLY and RESTART_REQUIRED are returned with 400 by their endpoints (ResponseEntity.badRequest()), while code-name resolution would derive 403 — the divergence is tracked as a pending decision (issue #405) and this table registers the observed values. The previous version also listed VALIDATION_ERROR (only the ValidationFailureType enum constant, never emitted as a response code) and INVALID_PARAMETER / MISSING_PARAMETER / INVALID_FORMAT (no match in the codebase); all four were removed.

Business Error Codes¶

HTTP Status: 409 Conflict

Conflicts surface as CONFLICT_STATE (mapped from exceptions) plus the per-endpoint variants that share the prefix — CONFLICT_EXISTS / CONFLICT_BUILTIN; there is no bare CONFLICT. ApiException.resolveStatus maps every CONFLICT* code to 409.

Rate Limit Error Codes¶

HTTP Status: 429 Too Many Requests (admin surface) · 401 (API Key validation chain)

⚠️ One code, two statuses on two real paths (issue #404, pending decision): ① the admin rate limiter (AdminApiRateLimiter) writes a flat 429 body {"code":"RATE_LIMIT_EXCEEDED","message":...}; ② the API Key validation chain (ApiKeyValidator → FullValidationResult.toException()) wraps the same code in an AuthenticationException, so the client receives 401. A client branching on status must handle both.

There is no X-RateLimit-Reset / X-RateLimit-Remaining header anywhere in the codebase; quota rejections write Retry-After and the X-Quota-* family (limit / remaining / window). GLOBAL_RATE_LIMIT / SERVICE_RATE_LIMIT / INSTANCE_RATE_LIMIT were removed from this table: the first two have no match in the codebase, and the third is only a JPA table name.

System Error Codes¶

HTTP Status: 500 Internal Server Error

⚠️ RULE_COMPILATION_FAILED belongs to the same family as the three authorization codes above: it is declared in SanitizationException and has no emission site (its factory method is only called by unit tests), so it was removed from this table. A rule compilation failure currently surfaces as SANITIZATION_FAILED or INVALID_SANITIZATION_RULE. CONFIGURATION_ERROR / DATABASE_ERROR / CACHE_ERROR from the previous version have no match either: configuration, database and cache failures all surface as INTERNAL_ERROR (which is also the resolver's fallback for any code that matches none of its rules).

Service Unavailable¶

HTTP Status: 503 Service Unavailable

Downstream Service Error Codes¶

HTTP Status: the downstream status verbatim (commonly 502/503/504; a downstream 401 is normalized onto the 401 authentication branch)

This code's HTTP status is not fixed: SecurityExceptionHandler writes the error body with the downstream status verbatim ⇒ the registry records its status as context-dependent (it is not one of 502/503). The previous version listed 5xx / 502 / 503 / 504 as "error code patterns"; those are neither codes nor values this gateway emits.

Error Handling Best Practices¶

1. Client-Side Error Handling¶

// JavaScript Example
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':
        // Re-authentication required
        window.location.href = '/login';
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Back off and retry (the admin surface sends Retry-After with its 429)
        await sleep((Number(response.headers.get('Retry-After')) || 1) * 1000);
        return retryRequest();
      default:
        showError(data.message ?? data.error?.message);
    }
    return;
  }

  return data.data;
}

2. Server-Side Error Handling¶

// Java Example
@RestControllerAdvice
public class ErrorHandler {

    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity<ErrorResponse> handleAuthException(AuthenticationException ex) {
        // The status comes from the exception (the authentication render path in the registry)
        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. Error Logging¶

// Log error information
log.error("Authentication failed: errorCode={}, message={}",
    ex.getErrorCode(), ex.getMessage());

Changelog¶

Last updated: 2026-10-15