Error Codes Reference¶

Document Version: 1.0.0 Last Updated: 2026-05-25 Applicable Version: v2.7.34+ 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.

Error Response Format¶

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

HTTP Status Code Mapping¶

Authentication Error Codes¶

HTTP Status: 401 Unauthorized

Example Response:

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

Authorization Error Codes¶

HTTP Status: 403 Forbidden

Example Response:

{
  "success": false,
  "message": "Insufficient permissions, required: admin",
  "errorCode": "INSUFFICIENT_PERMISSIONS",
  "data": null
}

Sanitization Error Codes¶

HTTP Status: 500 Internal Server Error

Example Response:

{
  "success": false,
  "message": "Data sanitization failed: unsupported content format",
  "errorCode": "SANITIZATION_FAILED",
  "data": null
}

Resource Error Codes¶

HTTP Status: 404 Not Found

Validation Error Codes¶

HTTP Status: 400 Bad Request

Business Error Codes¶

Downstream Service Error Codes¶

HTTP Status: 502/503

Rate Limit Error Codes¶

HTTP Status: 429 Too Many Requests

Circuit Breaker Error Codes¶

System Error Codes¶

HTTP Status: 500 Internal Server Error

Error Handling Best Practices¶

1. Client-Side Error Handling¶

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

  if (!data.success) {
    switch (data.errorCode) {
      case 'INVALID_API_KEY':
      case 'EXPIRED_API_KEY':
      case 'INVALID_JWT_TOKEN':
      case 'EXPIRED_JWT_TOKEN':
        // Redirect to login page
        window.location.href = '/login';
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        const resetTime = response.headers.get('X-RateLimit-Reset');
        await sleep(resetTime * 1000);
        return retryRequest();
        break;
      default:
        // Show error message
        showError(data.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) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
            .body(new ErrorResponse(ex.getMessage(), ex.getErrorCode()));
    }

    @ExceptionHandler(RateLimitExceededException.class)
    public ResponseEntity<ErrorResponse> handleRateLimit(RateLimitExceededException ex) {
        return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
            .header("X-RateLimit-Reset", ex.getResetTime())
            .body(new ErrorResponse("Too many requests", "RATE_LIMIT_EXCEEDED"));
    }
}

3. Error Logging¶

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

Quick Reference by Status Code¶

Changelog¶

Last updated: 2026-05-25