Error Handling

API Version: 1.0.0

Overview

DoneIsBetter SSO uses standard HTTP status codes along with detailed error messages to help you understand and handle errors effectively. This guide covers common errors, how to handle them, and best practices for error management.

HTTP Status Codes

Status Code	Description	Common Scenarios
`400`	Bad Request	Invalid input parameters, malformed request body
`401`	Unauthorized	Invalid or expired session, authentication required
`403`	Forbidden	Insufficient permissions, unauthorized domain
`404`	Not Found	Resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error

Error Response Format

All error responses follow a consistent format:

{
  "error": "ERROR_TYPE",
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional error-specific information
  }
}

Common Error Types

VALIDATION_ERROR - Input validation failed
AUTH_ERROR - Authentication-related errors
PERMISSION_ERROR - Permission-related errors
RATE_LIMIT_ERROR - Rate limit exceeded
SERVER_ERROR - Internal server errors

Error Handling Examples

Session Validation

try {
  const session = await sso.validateSession();
  if (session.isValid) {
    // Handle valid session
  }
} catch (error) {
  if (error.code === 'SESSION_EXPIRED') {
    // Redirect to login
    sso.redirectToLogin();
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Handle rate limiting
    console.error('Too many requests, please try again later');
  } else {
    // Handle other errors
    console.error('Session validation failed:', error.message);
  }
}

Authentication Errors

try {
  await sso.authenticate(username);
} catch (error) {
  switch (error.code) {
    case 'INVALID_CREDENTIALS':
      showError('Invalid username or password');
      break;
    case 'ACCOUNT_LOCKED':
      showError('Account is locked. Please contact support.');
      break;
    case 'DOMAIN_NOT_ALLOWED':
      showError('Your domain is not authorized for SSO.');
      break;
    default:
      showError('Authentication failed: ' + error.message);
  }
}

Best Practices

Always handle errors: Don't let errors propagate to users without proper handling and messaging.
Implement retry logic: For transient errors, implement exponential backoff retry logic.
Log errors: Maintain proper error logging for debugging and monitoring.
User-friendly messages: Transform technical error messages into user-friendly notifications.
Session recovery: Implement graceful session recovery when possible.

// Example of retry logic with exponential backoff
async function retryOperation(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        // Wait with exponential backoff
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Error Monitoring

DoneIsBetter SSO provides error monitoring endpoints to help you track and debug issues in your integration:

// Enable error monitoring
sso.enableMonitoring({
  reportErrors: true,
  logLevel: 'warn',
  errorCallback: (error) => {
    // Custom error handling
    console.error('SSO Error:', error);
    analytics.trackError(error);
  }
});

Troubleshooting Guide

Common Issues

Session doesn't persist:
- Check CORS configuration
- Verify cookie settings
- Ensure proper domain registration
Frequent authentication errors:
- Verify network connectivity
- Check rate limiting status
- Validate domain registration
Permission issues:
- Verify user roles and permissions
- Check domain authorization
- Review access logs