@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/providers/sagemaker/error-constants.js

@@ -0,0 +1,227 @@
+/**
+ * Error message constants and templates for Amazon SageMaker Provider
+ *
+ * This module contains all error message templates, prefixes, and constants
+ * used throughout the SageMaker provider for consistent error handling.
+ */
+/**
+ * Error message prefixes for different error types
+ */
+export const ERROR_MESSAGE_PREFIXES = {
+    VALIDATION: "Invalid request parameters",
+    MODEL: "Model execution error",
+    INTERNAL: "Internal server error",
+    SERVICE_UNAVAILABLE: "SageMaker service is temporarily unavailable",
+    THROTTLING: "Request rate limit exceeded",
+    CREDENTIALS: "AWS credentials are invalid or missing",
+    NETWORK: "Network error while connecting to SageMaker",
+    ENDPOINT_NOT_FOUND: "SageMaker endpoint not found",
+    VALIDATION_FIELD: "Validation failed for",
+    CREDENTIALS_SETUP: "AWS credentials error",
+    NETWORK_CONNECTION: "Network error",
+};
+/**
+ * Detailed error message templates for user guidance
+ */
+export const ERROR_MESSAGE_TEMPLATES = {
+    VALIDATION_ERROR: `❌ SageMaker Request Validation Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check your request parameters and format
+2. Verify the endpoint name is correct
+3. Ensure your request body matches the expected model format
+4. Validate that required parameters are included
+
+💡 Tips:
+- Double-check the endpoint name spelling
+- Ensure JSON format is valid if using JSON content type
+- Verify parameter types match model expectations`,
+    MODEL_ERROR: `❌ SageMaker Model Execution Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check if the model is properly deployed and in 'InService' status
+2. Verify your input format matches what the model expects
+3. Ensure input size is within model limits
+4. Check if the model container is healthy
+
+💡 Tips:
+- Try with a simpler input to test model health
+- Check CloudWatch logs for detailed model errors
+- Verify model dependencies are properly installed`,
+    INTERNAL_ERROR: `❌ SageMaker Internal Server Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Retry the request after a short delay
+2. Check AWS Service Health Dashboard
+3. Verify your endpoint is still active and healthy
+4. Contact AWS support if issue persists
+
+💡 Tips:
+- This is usually a temporary issue
+- Implement exponential backoff for retries
+- Check if other endpoints are working`,
+    SERVICE_UNAVAILABLE: `❌ SageMaker Service Temporarily Unavailable{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Wait and retry after a few seconds
+2. Check AWS region status
+3. Verify your endpoint hasn't been deleted
+4. Check if you've hit account limits
+
+💡 Tips:
+- Service issues are usually temporary
+- Implement retry logic with backoff
+- Monitor AWS Service Health Dashboard`,
+    CREDENTIALS_ERROR: `❌ AWS Credentials Error{endpointContext}
+
+{originalMessage}
+
+🔧 Required Steps:
+1. Verify AWS_ACCESS_KEY_ID is set correctly
+2. Verify AWS_SECRET_ACCESS_KEY is set correctly
+3. Check AWS_SESSION_TOKEN if using temporary credentials
+4. Ensure credentials have SageMaker permissions
+
+🔑 Required IAM Permissions:
+- sagemaker:InvokeEndpoint
+- sagemaker:InvokeEndpointWithResponseStream
+- sagemaker:DescribeEndpoint (optional, for debugging)
+
+💡 Setup Help:
+- Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
+- Check IAM user has necessary permissions
+- Verify credentials haven't expired`,
+    NETWORK_ERROR: `❌ Network Connection Error{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Check your internet connection
+2. Verify firewall/proxy settings
+3. Try different DNS servers
+4. Check if SageMaker service is accessible from your network
+
+💡 Network Troubleshooting:
+- Test connectivity to other AWS services
+- Check for VPC/subnet restrictions if running in AWS
+- Verify security group rules allow outbound HTTPS`,
+    ENDPOINT_NOT_FOUND: `❌ SageMaker Endpoint Not Found{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Verify the endpoint name is spelled correctly
+2. Check if the endpoint exists in the correct AWS region
+3. Ensure the endpoint is in 'InService' status
+4. Verify you have permissions to access the endpoint
+
+💡 Endpoint Management:
+- List endpoints: aws sagemaker list-endpoints
+- Check status: aws sagemaker describe-endpoint --endpoint-name <name>
+- Ensure endpoint is deployed in the same region`,
+    THROTTLING_ERROR: `❌ Request Rate Limit Exceeded{endpointContext}
+
+{originalMessage}
+
+🔧 Common Solutions:
+1. Implement exponential backoff retry logic
+2. Reduce request rate
+3. Consider using batch inference for large workloads
+4. Request higher limits from AWS support if needed
+
+💡 Rate Limiting Tips:
+- Space out requests over time
+- Use batch processing when possible
+- Monitor your request patterns
+- Consider auto-scaling your endpoint`,
+    UNKNOWN_ERROR: `❌ Unknown SageMaker Error{endpointContext}
+
+{originalMessage}
+
+🔧 General Troubleshooting:
+1. Check AWS credentials and permissions
+2. Verify endpoint name and status
+3. Check network connectivity
+4. Review request format and parameters
+
+💡 Additional Help:
+- Check CloudWatch logs for detailed errors
+- Verify SageMaker service health
+- Consult AWS SageMaker documentation
+- Contact AWS support for persistent issues`,
+    DEFAULT: `❌ SageMaker Error{endpointContext}
+
+{originalMessage}
+
+🔧 General Troubleshooting:
+1. Check AWS credentials and permissions
+2. Verify endpoint name and status
+3. Check network connectivity
+4. Review request format and parameters
+
+💡 Additional Help:
+- Check CloudWatch logs for detailed errors
+- Verify SageMaker service health
+- Consult AWS SageMaker documentation
+- Contact AWS support for persistent issues`,
+};
+/**
+ * Retry delay constants for different error types (in milliseconds)
+ */
+export const RETRY_DELAYS = {
+    THROTTLING_ERROR: 5000, // 5 seconds for throttling
+    SERVICE_UNAVAILABLE: 2000, // 2 seconds for service issues
+    NETWORK_ERROR: 1000, // 1 second for network issues
+    DEFAULT: 1000, // Default 1 second
+};
+/**
+ * List of retryable AWS SDK error names and conditions
+ */
+export const RETRYABLE_ERROR_CONDITIONS = {
+    ERROR_NAMES: [
+        "ServiceUnavailable",
+        "InternalFailure",
+        "ThrottlingException",
+        "NetworkingError",
+    ],
+    ERROR_MESSAGE_KEYWORDS: [
+        "timeout",
+        "throttl",
+        "unavailable",
+        "internal",
+        "network",
+    ],
+};
+/**
+ * AWS SDK error name mappings to SageMaker error codes
+ */
+export const AWS_ERROR_MAPPINGS = {
+    ValidationException: "VALIDATION_ERROR",
+    ModelError: "MODEL_ERROR",
+    InternalFailure: "INTERNAL_ERROR",
+    ServiceUnavailable: "SERVICE_UNAVAILABLE",
+    ThrottlingException: "THROTTLING_ERROR",
+    CredentialsError: "CREDENTIALS_ERROR",
+    NetworkingError: "NETWORK_ERROR",
+};
+/**
+ * Common error message keywords for pattern matching
+ */
+export const ERROR_KEYWORDS = {
+    VALIDATION: ["validation"],
+    MODEL: ["model error"],
+    INTERNAL: ["internal"],
+    SERVICE_UNAVAILABLE: ["unavailable"],
+    THROTTLING: ["throttl"],
+    CREDENTIALS: ["credential"],
+    NETWORK: ["network"],
+    ENDPOINT_NOT_FOUND: ["endpoint", "not found"],
+};

package/dist/client/providers/sagemaker/errors.js

@@ -0,0 +1,299 @@
+/**
+ * Error handling system for Amazon SageMaker Provider
+ *
+ * This module provides comprehensive error handling, categorization,
+ * and user-friendly error messages for SageMaker operations.
+ */
+import { ERROR_MESSAGE_TEMPLATES, ERROR_MESSAGE_PREFIXES, RETRY_DELAYS, RETRYABLE_ERROR_CONDITIONS, ERROR_KEYWORDS, } from "./error-constants.js";
+/**
+ * Custom error class for SageMaker-specific errors
+ */
+export class SageMakerError extends Error {
+    code;
+    statusCode;
+    cause;
+    endpoint;
+    requestId;
+    retryable;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "SageMakerError";
+        this.code = options.code ?? "UNKNOWN_ERROR";
+        this.statusCode = options.statusCode;
+        this.cause = options.cause;
+        this.endpoint = options.endpoint;
+        this.requestId = options.requestId;
+        this.retryable = options.retryable ?? false;
+        // Capture stack trace if available
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SageMakerError);
+        }
+    }
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            cause: this.cause,
+            endpoint: this.endpoint,
+            requestId: this.requestId,
+            retryable: this.retryable,
+            stack: this.stack,
+        };
+    }
+    /**
+     * Get user-friendly error message with troubleshooting guidance
+     */
+    getUserFriendlyMessage() {
+        return getSageMakerErrorGuidance(this.code, this.message, this.endpoint);
+    }
+    /**
+     * Check if this error type is retryable
+     */
+    isRetryable() {
+        return this.retryable;
+    }
+    /**
+     * Get recommended retry delay in milliseconds
+     */
+    getRetryDelay() {
+        return (RETRY_DELAYS[this.code] ||
+            RETRY_DELAYS.DEFAULT);
+    }
+}
+/**
+ * Main error handler for SageMaker operations
+ *
+ * @param error - Original error from AWS SDK or other operations
+ * @param endpoint - Endpoint name where error occurred (optional)
+ * @returns Categorized SageMakerError with user guidance
+ */
+export function handleSageMakerError(error, endpoint) {
+    // Handle cases where error is already a SageMakerError
+    if (error instanceof SageMakerError) {
+        return error;
+    }
+    // Handle standard Error objects
+    if (error instanceof Error) {
+        const errorName = error.name;
+        const errorMessage = error.message.toLowerCase();
+        // AWS SDK specific errors using centralized constants
+        if (errorName === "ValidationException" ||
+            ERROR_KEYWORDS.VALIDATION.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.VALIDATION}: ${error.message}`, {
+                code: "VALIDATION_ERROR",
+                statusCode: 400,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: false,
+            });
+        }
+        if (errorName === "ModelError" ||
+            ERROR_KEYWORDS.MODEL.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.MODEL}: ${error.message}`, {
+                code: "MODEL_ERROR",
+                statusCode: 500,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: false,
+            });
+        }
+        if (errorName === "InternalFailure" ||
+            ERROR_KEYWORDS.INTERNAL.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.INTERNAL}: ${error.message}`, {
+                code: "INTERNAL_ERROR",
+                statusCode: 500,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: true,
+            });
+        }
+        if (errorName === "ServiceUnavailable" ||
+            ERROR_KEYWORDS.SERVICE_UNAVAILABLE.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.SERVICE_UNAVAILABLE}: ${error.message}`, {
+                code: "SERVICE_UNAVAILABLE",
+                statusCode: 503,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: true,
+            });
+        }
+        if (errorName === "ThrottlingException" ||
+            ERROR_KEYWORDS.THROTTLING.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.THROTTLING}: ${error.message}`, {
+                code: "THROTTLING_ERROR",
+                statusCode: 429,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: true,
+            });
+        }
+        if (errorName === "CredentialsError" ||
+            ERROR_KEYWORDS.CREDENTIALS.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.CREDENTIALS}: ${error.message}`, {
+                code: "CREDENTIALS_ERROR",
+                statusCode: 401,
+                cause: error,
+                endpoint,
+                requestId: undefined,
+                retryable: false,
+            });
+        }
+        if (errorName === "NetworkingError" ||
+            ERROR_KEYWORDS.NETWORK.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.NETWORK}: ${error.message}`, {
+                code: "NETWORK_ERROR",
+                statusCode: 0,
+                cause: error,
+                endpoint,
+                requestId: undefined,
+                retryable: true,
+            });
+        }
+        if (ERROR_KEYWORDS.ENDPOINT_NOT_FOUND.every((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.ENDPOINT_NOT_FOUND}: ${error.message}`, {
+                code: "ENDPOINT_NOT_FOUND",
+                statusCode: 404,
+                cause: error,
+                endpoint,
+                requestId: extractRequestId(error),
+                retryable: false,
+            });
+        }
+        // Generic error handling
+        return new SageMakerError(error.message, {
+            code: "UNKNOWN_ERROR",
+            statusCode: 500,
+            cause: error,
+            endpoint,
+            requestId: extractRequestId(error),
+            retryable: false,
+        });
+    }
+    // Handle non-Error objects
+    const errorMessage = typeof error === "string" ? error : "Unknown error occurred";
+    return new SageMakerError(errorMessage, {
+        code: "UNKNOWN_ERROR",
+        statusCode: 500,
+        cause: undefined,
+        endpoint,
+        requestId: undefined,
+        retryable: false,
+    });
+}
+/**
+ * Extract request ID from AWS SDK error for debugging
+ *
+ * @param error - Error object that might contain request ID
+ * @returns Request ID if found, undefined otherwise
+ */
+function extractRequestId(error) {
+    const errorAny = error;
+    return (errorAny.requestId ||
+        errorAny.RequestId ||
+        errorAny.$metadata?.requestId ||
+        undefined);
+}
+/**
+ * Get user-friendly error guidance based on error code
+ *
+ * @param code - SageMaker error code
+ * @param originalMessage - Original error message
+ * @param endpoint - Endpoint name (optional)
+ * @returns User-friendly error message with troubleshooting steps
+ */
+function getSageMakerErrorGuidance(code, originalMessage, endpoint) {
+    const endpointContext = endpoint ? ` (endpoint: ${endpoint})` : "";
+    // Get template for the error code, falling back to default
+    const template = ERROR_MESSAGE_TEMPLATES[code] || ERROR_MESSAGE_TEMPLATES.DEFAULT;
+    // Replace placeholders in the template
+    return template
+        .replace("{endpointContext}", endpointContext)
+        .replace("{originalMessage}", originalMessage);
+}
+/**
+ * Create a validation error for configuration issues
+ *
+ * @param message - Validation error message
+ * @param field - Configuration field that failed validation
+ * @returns SageMakerError with validation details
+ */
+export function createValidationError(message, field) {
+    const fullMessage = field
+        ? `${ERROR_MESSAGE_PREFIXES.VALIDATION_FIELD} '${field}': ${message}`
+        : message;
+    return new SageMakerError(fullMessage, {
+        code: "VALIDATION_ERROR",
+        statusCode: 400,
+        retryable: false,
+    });
+}
+/**
+ * Create a credentials error with setup guidance
+ *
+ * @param message - Credentials error message
+ * @returns SageMakerError with credentials guidance
+ */
+export function createCredentialsError(message) {
+    return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.CREDENTIALS_SETUP}: ${message}`, {
+        code: "CREDENTIALS_ERROR",
+        statusCode: 401,
+        retryable: false,
+    });
+}
+/**
+ * Create a network error with connectivity guidance
+ *
+ * @param message - Network error message
+ * @param endpoint - Endpoint that failed to connect
+ * @returns SageMakerError with network guidance
+ */
+export function createNetworkError(message, endpoint) {
+    return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.NETWORK_CONNECTION}: ${message}`, {
+        code: "NETWORK_ERROR",
+        statusCode: 0,
+        endpoint,
+        retryable: true,
+    });
+}
+/**
+ * Check if an error is retryable based on its characteristics
+ *
+ * @param error - Error to check
+ * @returns True if the error suggests a retry might succeed
+ */
+export function isRetryableError(error) {
+    if (error instanceof SageMakerError) {
+        return error.isRetryable();
+    }
+    if (error instanceof Error) {
+        const errorMessage = error.message.toLowerCase();
+        const errorName = error.name;
+        // Check against retryable error names and message keywords
+        return (RETRYABLE_ERROR_CONDITIONS.ERROR_NAMES.includes(errorName) ||
+            RETRYABLE_ERROR_CONDITIONS.ERROR_MESSAGE_KEYWORDS.some((keyword) => errorMessage.includes(keyword)));
+    }
+    return false;
+}
+/**
+ * Get recommended retry delay for an error
+ *
+ * @param error - Error to get retry delay for
+ * @param attempt - Current retry attempt number (for exponential backoff)
+ * @returns Recommended delay in milliseconds
+ */
+export function getRetryDelay(error, attempt = 1) {
+    if (error instanceof SageMakerError) {
+        return error.getRetryDelay() * Math.pow(2, attempt - 1);
+    }
+    // Default exponential backoff
+    return 1000 * Math.pow(2, attempt - 1);
+}