Error Handling

Handle errors and exceptions in Scalekit SDKs with proper error patterns and recovery strategies

Understand how to handle errors and exceptions in Scalekit SDKs. Proper error handling ensures your application gracefully handles authentication failures, network issues, and invalid requests.

Common Error Types

Scalekit SDKs return errors in these categories:

Error Type	Description	Recovery Strategy
Authentication Errors	Invalid credentials, expired codes	Redirect to login, refresh tokens
Validation Errors	Invalid parameters, missing fields	Fix request parameters
Network Errors	Timeout, connection failures	Retry with exponential backoff
Configuration Errors	Invalid SDK setup	Check environment variables
Authorization Errors	Insufficient permissions	Request proper scopes

Error Response Format

Errors include these properties:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired",
  "status": 400
}

Field	Description
error	Error code identifier
error_description	Human-readable error message
status	HTTP status code

Authentication Errors

Invalid Grant

Authorization code expired or already used:

Invalid Client

Invalid client credentials:

Token Expired

Access token has expired:

Validation Errors

Missing Required Parameters

Invalid State Parameter

CSRF protection validation:

Network Errors

Connection Timeout

Handle network timeouts with retry logic:

Error Logging

Log errors for debugging and monitoring:

User-Friendly Error Messages

Display helpful error messages to users:

Error mapping

const ERROR_MESSAGES = {
  invalid_grant: 'Your login session has expired. Please try again.',
  invalid_client: 'Configuration error. Please contact support.',
  access_denied: 'You denied access to your account.',
  network_error: 'Network connection failed. Please check your internet.',
  session_expired: 'Your session has expired. Please sign in again.',
  invalid_state: 'Security validation failed. Please try again.',
};

function getUserMessage(errorCode) {
  return ERROR_MESSAGES[errorCode] || 'An unexpected error occurred. Please try again.';
}

// Usage
try {
  const authResult = await scalekit.authenticateWithCode(code, redirectUri);
} catch (error) {
  const userMessage = getUserMessage(error.code);
  return res.redirect(`/login?error=${encodeURIComponent(userMessage)}`);
}

Best Practices

1. Always validate input - Check for required parameters before making SDK calls
2. Implement retry logic - Handle transient network errors with exponential backoff
3. Log errors properly - Include context for debugging without exposing sensitive data
4. Provide user feedback - Show clear, actionable error messages to users
5. Monitor error rates - Track error patterns to identify systemic issues
6. Handle CSRF attacks - Always validate state parameter in OAuth callbacks
7. Secure error responses - Never expose internal errors or stack traces to users
8. Test error scenarios - Write tests for common error conditions

Next Steps

• Explore code examples
• Review SDK configuration
• View SDK overview