Skip to main content
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 TypeDescriptionRecovery Strategy
Authentication ErrorsInvalid credentials, expired codesRedirect to login, refresh tokens
Validation ErrorsInvalid parameters, missing fieldsFix request parameters
Network ErrorsTimeout, connection failuresRetry with exponential backoff
Configuration ErrorsInvalid SDK setupCheck environment variables
Authorization ErrorsInsufficient permissionsRequest proper scopes

​
Error Response Format

Errors include these properties: 
{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired",
  "status": 400
}
FieldDescription
errorError code identifier
error_descriptionHuman-readable error message
statusHTTP 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

                Build docs developers (and LLMs) love

                Get started for freeTalk to us